D2.2 Connectivity and Information Management

Transcription

1 Grant Agreement number: Project acronym: emar Project title: e Maritime Strategic Framework and Simulation based Validation Funding Scheme: SST D2.2 Connectivity and Information Management Due date of deliverable: 28/02/2014 Actual submission date: 03/02/2014 Start date of project: 01/02/2012 Duration: 36M Organisation name of lead contractor for this deliverable: ebos Technologies Ltd Revision : Final Project co funded by the European Commission within the Seventh Framework Programme ( ) Dissemination Level RE Restricted to a group specified by the consortium (including the Commission Services) PU Public

2 Page 2 of 77

3 This emar report is licenced under a Creative Commons licence Attribution-NonCommercial-ShareAlike 4.0 International

4 Contents EXECUTIVE SUMMARY... 5 GLOSSARY INTRODUCTION Overview of the D2.2 Deliverable Objectives of the D2.2 Deliverable THE EMAR SYSTEM ARCHITECTURE E Maritime Systems Framework (EMSF) emar Technology Ecosystem emar Architecture Layers EMAR CONNECTIVITY ARCHITECTURE AND MESSAGE EXCHANGE Connectivity Architecture Overview emar Message Exchange Focus Areas Challenges to e Maritime Message Exchange emar Connectivity Services emar Connectivity Standard Models EMAR ACCESS POINTS Overview Exchange Security: Quality and Reliability Ownership of Information THE EMAR API LIBRARY Port Operations Transport Logistics Third Party Digital Services Ship Operations CONCLUSION REFERENCES APPENDIX A EMAR API LIBRARY APPENDIX B EMAR ACCESS POINTS B.2 The Service Metadata Locator and Service Metadata Publishing B.3 Process Identifier B.4 The Lightweight Message Exchange Profile B.5 Secure Trusted Asynchronous Reliable Transport (START) B.6 emar Access Points: Component View B.7 emar Access Points: Business View B.8 emar Access Points: Message Channels Page 3 of 77

5 Document Summary Information Authors and contributors Initial Name Organisation Role SC Dr SteliosChristofi ebos Author AT Aaron Trant ebos Author PC Phanos Christofi ebos Author RP Ritsa Pitta ebos Author CK Charalambos Koptides ebos Author ML Maria Lambrou ILS Contributing Author ZP Zissis Palaskas ILS Contributing Author GK Gerasimos Kouloumbis CLMS Contributing Author Revision history Revision Date Who Comment Final V1 03/02/14 RP Final release Quality control Role Who Date Quality manager JTP 03/02/2014 Project manager JG 03/02/2014 Technical manager TK 03/02/2014 Disclaimer The content of the publication herein is the sole responsibility of the publishers and it does not necessarily represent the views expressed by the European Commission or its services. While the information contained in the documents is believed to be accurate, the authors(s) or any other participant in the EMAR consortium make no warranty of any kind with regard to this material including, but not limited to the implied warranties of merchantability and fitness for a particular purpose. Neither the emar Consortium nor any of its members, their officers, employees or agents shall be responsible or liable in negligence or otherwise howsoever in respect of any inaccuracy or omission herein. Without derogating from the generality of the foregoing neither the emar Consortium nor any of its members, their officers, employees or agents shall be liable for any direct or indirect or consequential loss or damage caused by or arising from any information advice or inaccuracy or omission herein. Page 4 of 77

6 Executive Summary The present document delivers the work carried out in the task T2.2 Connectivity and Information Management Services, which focus on the implementation of emar software platform APIs (ST2.2.1). This document provides a description of the emar software Ecosystem, the principle of Access Points and how the emar Project will integrate and enhance Information Management tools according to the emar architecture. Moreover, it presents a comprehensive description regarding several operations related with Maritime domain and how these functionalities can be used from business users and what are the benefits in terms of cost and efficiency. The outputs from this task will feed D2.5 with standardization requirements for communication security and common information sharing. Page 5 of 77

7 List of Tables Figure 1.1: emar Connectivity Architecture Overview Figure 2.1: emar system to service publication / access through Ecosystem Architecture Figure 2.2: emar Architecture Layers Figure 3.1: emar Connectivity of Stakeholders though the Ecosystem, using Access Points Table 3.1: Message exchange areas for logistics chain Table 3.2: Message exchange areas for ship operations Table 3.3: Port reporting messages Table 5.1: Method Parameters Table 5.2: Method Reponse Table 5.3: Method Response Errors Table 5.4: Method Return Values Figure 5.1: Port Operations in emar Ecosystem Table 5.5: PCS Operations for Login and Administration Services Table 5.6: PCS opearations for terminal instruction services Figure 5.2: Transport Logistics Operations in emar Ecosystem Table 5.7: Operations for Transport Logistics Table 5.8: Operations for erecruitment Figure 5.3: emar erecruitment as part of Crew Management Table 5.9: Operations for Maritime Financials Figure 5.4: Ship Operations in emar Ecosystem Table 5.10: Operations for Ship Operations Table A.1.1: Login Parameters Table A.1.2: Login Response Table A.1.3: Login Response Errors Table A.1.4: Login Return Value Table A.1.5: Check Session Parameters Table A.1.6: Check Session Response Table A.1.7: Check Session Response Error Table A.1.8: Change Password Parameters Table A.1.9: Change Password Response Table A.1.10: Change Password Response Errors Table A.2.1: Get TVA Model Equipment Parameters Table A.2.2: Get TVA Model Equipment Response Table A.2.3: Get TVA Model Equipment Response Errors Table A.2.4: Get TVA Model Equipment Return Value Table A.2.5: Search Equipments Parameters Table A.2.6: Search Equipments Response Table A.2.7: Search Equipments Response Errors Table A.2.8: Search Equipments Return Value Table A.2.9: Save Equipment List Document Parameters Page 6 of 77

8 Table A.2.10: Save Equipment List Document Response Table A.2.11: Save Equipment List Document Response Errors Table A.2.12: Save Equipment List Document Return Value Table A.3.1: Tracking & Tracing Services Parameters Table A.3.2: Tracking & Tracing Services Response Table A.3.3: Tracking & Tracing Services Response Errors Table A.3.4: Tracking & Tracing Services Return Value Table A.4.1: Find Candidates Crew Applications Parameters Table A.4.2: Find Candidates Crew Applications Response Table A.4.3: Find Candidates Crew Applications Response Errors Table A.4.4: Find Candidates Crew Applications Return Value Table A.4.5: Find Recruitment Requests Parameters Table A.4.6: Find Recruitment Requests Response Table A.4.7: Find Recruitment Requests Response Errors Table A.4.8: Find Recruitment Requests Return Value Table A.5.1: Maritime Accounting and M.I.S. Parameters Table A.5.2: Maritime Accounting and M.I.S. Response Table A.5.3: Maritime Accounting and M.I.S. Response Errors Table A.5.4: Budgeting System Parameters Table A.5.5: Budgeting System Response Table A.5.6: Budgeting System Response Errors Table A.5.7: Payment Module Parameters Table A.5.8: Payment Module Response Table A.5.9: Payment Module Response Errors Table A.6.1: Ship Status Parameters Table A.6.2: Ship Status Response Table A.6.3: Ship Status Response Errors Table A.6.4: Parameters Table A.6.5: Ship Status Response Table A.6.6: Ship Status Response Errors Table A.6.7: Cargo Details Parameters Table A.6.8: Cargo Details Response Table A.6.9: Cargo Details Response Errors Figure B.1: Endpoint lookup with SMP and SML Figure B.2: The Lightweight Message Exchange [5] Figure B.3: The START Transport Protocol [3] Figure B.4: Tiered Component Diagram of the Access Point Figure B.5: Business view of Access Point Figure B.6: Participant sending a message for delivery (Operations on OutMC) Page 7 of 77

9 List of Figures Figure 1.1: emar Connectivity Architecture Overview Figure 2.1: emar system to service publication / access through Ecosystem Architecture Figure 2.2: emar Architecture Layers Figure 3.1: emar Connectivity of Stakeholders though the Ecosystem, using Access Points Figure 5.1: Port Operations in emar Ecosystem Figure 5.2: Transport Logistics Operations in emar Ecosystem Figure 5.3: emar erecruitment as part of Crew Management Figure 5.4: Ship Operations in emar Ecosystem Figure B.1: Endpoint lookup with SMP and SML Figure B.2: The Lightweight Message Exchange [5] Figure B.3: The START Transport Protocol [3] Figure B.4: Tiered Component Diagram of the Access Point Figure B.5: Business view of Access Point Figure B.6: Participant sending a message for delivery (Operations on OutMC) Glossary Maritime Stakeholders Maritime Logistics Chain Ecosystem Information Sharing API Web Service Access Point All the involved parties in the maritime industry: Shipping Companies, Shipping Agencies, Port Authorities, etc. All successive steps comprising a logistic process in maritime industry. A System of interconnecting and interacting parts. The exchange of data between a sender and a receiver. An Application Programming Interface (API) specifies how some software components interact with each other. A web service is a software function provided at a network address and allows the communication between two electronic devices over a network. A software function that enables the communication between electronic devices by providing a single connection point for controlled and secured access to information and services. Page 8 of 77

10 1 Introduction The emar project has been established to design solutions and define standards that will enable the participation of the European Maritime public, business and research community stakeholders in a knowledge sharing and economic development process. By exploiting existing technologies and components, it will support the implementation of the e Maritime Strategic Framework which will provide a common understanding and interpretation of the e Maritime concept along with a coherent view of the way Maritime Transport could operate in future. The emar Ecosystem and the enabling emar conceptual architecture are the key contributors to the above goals as they allow different stakeholder groups to convert their existing systems into services that can be combined in innovative solutions and facilitating exchange information in a trusted and efficient way. Furthermore, emar will demonstrate how a distributed Maritime information management system could be developed using in the main, existing technologies. This solution will greatly increase the interoperability between the different Maritime stakeholders, applications and services and so emar has reviewed communication strategies as part of its architectural blueprint. emar aims at integrating a wide range of services in order to cover the main operations performed in the Maritime community. This includes multi stakeholder, multifaceted strategic, economic, security, environmental and information technology perspectives. In this way emar will demonstrate how the Maritime industry can deal more effectively with Maritime threats and opportunities, in particular by promoting open innovation based on service oriented methodologies and software technology. Hence, emar addresses changes in the rationale and power balance underpinning Maritime governance and emerging e Maritime business models. Specifically, emar enhances the EU e Maritime Programme by providing: 1. The e Maritime Strategic Framework (EMSF) facilitates the achievement of the mission and strategic goals specified by a multi stakeholder orientated process and the relevant emar empirical testing/market surveys. This can be done by specifying a coherent view of the way Maritime Transport could operate at a future date (i.e. 2020). EMSF aims also at utilizing internet based solutions to support the development of an efficient and sustainable waterborne transport system fully integrated throughout Europe. Additionally through the EMSF, different performance imperatives will be addressed such as quality, flexibility, transparency and innovation in order to meet European economic, social and safety, security and environmental needs. 2. A secure low cost connectivity infrastructure in order to empower the European Maritime sector in offering efficient quality shipping services fully integrated in the overall European transport system. 3. A wide range of common digital resources which can be used in several of forms such as data, knowledge, applications, and optimizations services. This will also assist the execution of key activities of the EMSF framework which can be combined and used with existing applications, services and IT infrastructures by end users. 4. Impact analysis and recommendation on policy, standardization and future research. Page 9 of 77

11 Apart from the above background, another significant purpose of emar is to develop and empirically test, the vision of the e Maritime Ecosystem in an integrated, holistic and coherent manner. This can be done by addressing and challenging the prevailing Maritime governance structures. The emar project will simulate various policy and strategic cases by utilising the emar integrated e Maritime strategic framework and IT Ecosystem. Thus the emar Ecosystem provides a digital environment and a collection of domain models that are used by the emar Ecosystem participants for three basic goals: To confirm that the existing technologies and models will provide the appropriate environment for current and future Maritime operations in order to meet stakeholders strategic needs. To assist the development of new software applications and e services compatible with the EMSF that are available over the emar Ecosystem and platform. This will lead to the creation of a standardized connectivity infrastructure which will facilitate Maritime stakeholders to amplify their co operation capabilities. To facilitate the exchange of data between existing Maritime stakeholders and services within the Maritime Community that utilise the emar standard messages and associated Access Points In summary, the emar Ecosystem and its varied business and technical components will become the blueprint for Maritime e governance models. The emar Ecosystem with its conceptual framework which aligns the EMSF and emar architecture artifacts into a coherent whole that will provide a robust and usable roadmap that can be offered to Maritime logistics organizations in pursuit of sustainable operations in the digital era. 1.1 Overview of the D2.2 Deliverable The development of a sharing and collaboration culture in the Maritime professional and research community, Share more Develop less", is about the exchange and customization of applications among the key stakeholders which includes shipping and port organizations, agents and other Maritime entities and Maritime Logistics IT providers, over the emar Ecosystem. emar encourages the creation of innovative solutions along with the sharing and exchange of application software and Maritime know how. This is inspired by the use of free, open source software and participation in FOSS communities. Open source solutions can be viable for Maritime entities as they do not cost as much while being equally robust to proprietary software solutions. Where existing open software and applications are not available, cloud solutions can be attractive, cost effective solutions. Additionally, sharing on cloud based solutions and data is more easily deployed across large numbers of entities. Spending less, re using software and minimizing infrastructure investments is a pertinent value proposition of emar. Standardization of the communication solutions will also accelerate technology diffusion and market acceptance of the emar ecosystem. The primary value proposition of the emar Ecosystem is its potential as a technology oriented and long term enabler of Maritime clusters, in the digital era. It bridges the gap between the potential of technology oriented Maritime innovation and the needs and ambitions of Maritime Page 10 of 77

12 stakeholders. emar details the view of an open and user needs oriented innovation Ecosystem which is fit for purpose with the interests and needs of Maritime and Maritime multimodal freight transport stakeholders. These maritime stakeholders include shipping companies, manning agents, port authorities, logistics organizations and Maritime and transport IT vendors. The emar ecosystem is comprised of a cooperation framework and synergy linkages between internet research, Maritime policies and an open innovation framework include sharing of resources and experimentation facilities. The second value element of the emar Ecosystem is comprised of tools for the delivery of Maritime economic policies among stakeholders, namely ship owners, ship managers, shipbuilders, charterers, the Maritime administrations, port authorities and terminal operators, classification societies, insurers and financiers and also policy makers interested in concrete, business oriented solutions. All can exploit the EMSF and emar technical capabilities towards supporting or even fully realizing their objectives. At the heart of this deliverable lies the Access Point concept and technology which allows parties within the defined Maritime network to communicate using messages without the need for a centralized platform. Access points are analogous to , in which the user simply creates a message from their system, enters the destination address and presses send. Security using certificates define user profiles in address lists which defines the message standard that is used by the receiver. Users do not need to handle transformations/ mappings. This is taken care of in the Access Point or through services utilizing semantic technologies. The emaritime Network concept as illustrated: Figure 1.1: emar Connectivity Architecture Overview The key advantages provided by this solution are that it is; Single connection point for applications (data integration) Equivalent to secure e mail for e Maritime communications Page 11 of 77

13 1.2 Objectives of the D2.2 Deliverable WP2 of the emar project is aimed at producing the emar Software Maritime Ecosystem to facilitate the implementation of the e Maritime Strategic Framework. The e Maritime Ecosystem intends to offer an e Maritime SOA software Ecosystem including semantic technologies among stakeholder systems to enable different stakeholder groups develop upgraded e Maritime efficiency solutions. The Core of this solution is described in D2.2 deliverable which provides the service interfaces to support interoperability among the Maritime community and their systems. Specific objectives of D2.2 include: Referencing an e Maritime Ecosystem that extends the EMSF to specify in detail information interchanges and controls between stakeholders at different levels: transport networks, national authorities, EU agencies and international organizations. Provide connectivity and communication technologies that support each stakeholder group to interface existing applications with the emaritime Ecosystem. Provide specific intercommunication solutions that will form inputs into the development of simulation services to aid the visualization of end to end transport chain services, based on the EMSF models, with increased levels of automation in information exchanges between different stakeholders. Analysis of potential standardization activities focused on the common information sharing environment and communications security. The provided application protocols interfaces (APIs) from emar Ecosystem cover a wide range of business users by offering a broad range of typical emaritime services such as security, shipping, port operations, and transport logistics. Additionally, the emar APIs offer both dedicated and customizable services since use varies over time and a large number of stakeholders use them for different purposes. This has led to the establishment of a collaborative connectivity infrastructure which enables the communication between public and private parties and facilitates the development of the next generation of emaritime infrastructure, applications and services. Another objective of D2.2 is to provide a high level of compatibility in order to support each stakeholder group interface existing applications with the emar platform and Ecosystem which will result in an increase in collaboration capabilities. Additionally, the utilization of emar standard messages through the APIs will increase the levels of automation in information exchange and will also facilitate a shared understanding within emar Ecosystem between stakeholders. Thus, this deliverable aims to describe an upgraded connectivity and information management solution that will promote coherent, transparent, efficient and simplified solutions in support of cooperation, interoperability and consistency between member States, sectors, business and systems involved in the European Maritime Transport System. Page 12 of 77

14 2 The emar System Architecture 2.1 E Maritime Systems Framework (EMSF) The e Maritime Strategic Framework (EMSF) aims to create a common language enabling networking and computer supported co operation between the principal maritime transport stakeholder groups by bringing together into a coherent whole concepts, processes, standards and technologies. emar intends to establish a Pan European (and beyond) conceptual business architecture for everything to do with electronic communication within the area of Maritime transport, building on results from relevant previous projects. The intention of the emar conceptual business architecture, or the e Maritime Strategic Framework Specification (EMSF), is to describe generic solutions that can be used in all regions in Europe and globally. Despite the many differences between local, national, regional and global situations, the role responsibilities are by and large similar. Some core responsibilities are mandated by directives and agreements, and as a result are always present. For a role to accomplish its responsibilities it must execute one or more tasks. In reality, roles need to cooperate in order to perform required and coordinated actions. This cooperation implies exchange of information between roles. By means of the EMSF the information needs and communication requirements are analyzed for each role. The development of the emar Base Ecosystem is closely associated with standardization and the forms that this may take, often seen as a prerequisite for the development of e services. Based on the EMSF, a road map will be constructed showing milestones for the implementation of e Maritime services and their interaction with on going developments. The road map may also be augmented with assessments and projections for the future development of key enabling technologies such as telecommunications and surveillance systems. The emar Ecosystem (D2.1) will implement the following features: Specify the strategy and architecture for meeting both business and regulatory requirements/goals Improve compliance with data protection regulations, international rules, EU directives, standards and applicable confidentiality agreements Balance the interests, responsibilities and benefits of all stakeholders Standardize information required by supervisory bodies for regulatory compliance (and integration of that information in the supply chain) Identify key business drivers Define business, environmental and safety performance indicators Develop suitable organizational models Facilitate collaboration at regional, national and EU levels Be complementary to the Common Framework Page 13 of 77

15 2.2 emar Technology Ecosystem The emar Technology Ecosystem provides the technology infrastructure and integrated standards based technologies and infrastructures that are used to build an Ecosystem of Maritime Logistics Entities. Developing a loosely coupled environment involves Collaborative Planning, the composition of services in the Maritime logistic chains, the re planning of Maritime logistics chains, the optimization of resources, and monitoring of environmental Indexes [6]. The Technology Ecosystem architecture is loosely coupled and allows extreme scalability because the events do not know about the consequences of their cause and so, for instance, an RFID sensor fires an event when something happen but the sensor itself does not need to know that other objects will add information as a reaction to this event. The most relevant emar Ecosystem architecture features are the following: It envisions the creation of Ecosystems based of Persistent Logistic Objects. It shifts from a purely service oriented architecture to a more comprehensive virtual object oriented approach to provide solutions supporting autonomous decision capabilities. It is based on a semantically enriched architecture that supports not only the implementation of the internal services but also the integration with external applications and legacy systems. Semantics are used to enable global reasoning through the entire emar environment. Based on a standardized knowledge structure (ontology) extended with rules, relations and facts (actual measurements), trends and unusual deviations are determined and this contributes to the emar infrastructure and service intelligence. It implements semantic technologies to bridge differences within and between business communities. For the purpose of standardization, the Common Framework provides generic information models and message standards. The guidance of the participants to the overall development of emar Ecosystem SOA solutions will take place by adopting related Open Group Architecture Framework (TOGAF) principles and guidelines which constitute a framework for enterprise architectures widely used [1, 7, 10]. TOGAF's primary orientation is to support enterprise architecture implementation and maintenance, as in the case of collaborating emar Ecosystem participants. It considers having two concepts depending upon the context: A detailed plan of the system at component level to guide its implementation or/and a formal description of a system. The structure of components (such as emar Ecosystem components), their interrelationships, and the principles and guidelines governing their design and evolution over time A Technology Ecosystem relies on common interfaces and protocols to allow combining the different firms contributions. In this context, the emar Ecosystem architecture provides: Page 14 of 77

16 business applications to implement the business level innovations defined before; generic components to support data exchange between organizations and intelligent cargo object; an infrastructure, called a Hybrid Service Network for smart deployment of these applications and components. The lower infrastructure layer delivers crossfunctionalities for the implementation and deployment of these applications and components. The following figure shows how the users applications interact with the Ecosystem exposing data through published services and external devices. Page 15 of 77 Figure 2.1: emar system to service publication / access through Ecosystem Architecture This description of the emar Ecosystem is very high level. For a more detailed description of the Ecosystem and its components, refer to D2.1 emar Ecosystem Architecture and Technology. 2.3 emar Architecture Layers The emar Ecosystem prescribes a Maritime governance framework that guides Maritime stakeholders through a rapidly changing environment of technologies, societal determinants and business models. State of the art service oriented business IT alignment methods can be approached as pertaining into three layers: enterprise level, process level, and IT infrastructure level. The EMSF and emar Architecture, as developed in the emar project, primarily address this need for a systematic approach and constitute a set of distinct elements in all three above interlinked layers. To achieve this, the systems network architecture is proposed with the n tiered architecture in mind [2, 9, 12] and can be divided into 5 main layers, the Presentation Layer, the Service Layer, the Process Layer, the Domain Layer, and the Data Layer.

17 2.3.1 Presentation Layer Figure 2.2: emar Architecture Layers The user interface is a way for users to interact with the systems network and it helps in acquiring and validating data coming in from users. Model View Controller (MVC) is used for the implementation of user interfaces. MVC is a widely used software pattern that separates internal representations of information from the ways that information is presented to or accepted from the user. The user interface provides: A consistent development environment that is also used for creating other components of the Ecosystem. User interface data binding. Component based user interfaces with controls. Access to the security model Service Layer The hybrid network will provide services to other applications, as well as implementing features to support clients directly, through a services layer that exposes the whole functionality of the application Process Layer The Process layer reflects the macro level activities of the emar Ecosystem. The core processes will be encapsulated by workflow components that orchestrate one or more business components to implement a process. Page 16 of 77

18 2.3.4 Domain Layer The Domain Layer is a software engineering practice of compartmentalizing. This layer usually separates the application logic from other modules, such as the data access layer and user interface. This practice allows software application development to be more effectively split into teams, with each team working on a different tier simultaneously. Within a Domain Layer objects can further be partitioned into business processes (business activities) and business entities. Business process objects typically implement the controller pattern, i.e. they contain no data elements but have methods that orchestrate interaction among business entities. Business entities typically correspond to entities in the logical domain model, rather than the physical database model. Domain entities are a super set of data layer entities or data transfer objects, and may aggregate zero or more Data Transfer Objects Data Access Layer This layer governs all data access and converts relational data into objects and back again. It is a bridge between the Domain Model and the Data Source Model. The Ecosystem will implement its data access layer independently from the database server. It will support multiple database types, supporting and implementing all calls into the database repository, making it easier to port the Ecosystem to other database systems. Page 17 of 77

19 3 emar Connectivity Architecture and Message Exchange 3.1 Connectivity Architecture Overview The emar Ecosystem will support the development of interoperable applications which can exchange information with other applications using emar messages through existing standards or emar Access Points. The project focus can be specified with reference to the EMSF which has been materialized in a modular way to allow components to be developed with a clear focus and to promote flexible take up by stakeholders. The emar connectivity architecture primarily aims to facilitate the interfacing of different Maritime services with the emar Ecosystem and platform, through the information exchange between the different stakeholders groups. The key characteristics of the particular architecture such as reliability, flexibility, secure, low cost and availability will assist the EU Maritime transport sector to develop capabilities for managing highly dynamic business systems serving a wide range of stakeholder interests. The implementation of the connectivity architecture using the emar standard messages will also increase the interoperability and collaboration between public and private parties. The emar connectivity architecture consists of three categories of applications: Transport Networks applications, relating to ports, ship operations, and transport logistics; Third party digital services and applications. Administration and Regulatory Systems from EU, National Administrations and regulatory authorities The figure below shows how the connectivity infrastructure will contribute to the connectivity through Access Points and the collaboration between stakeholders letting them to optimize Maritime operations through collaborative processes and transparent access to services. Figure 3.1: emar Connectivity of Stakeholders though the Ecosystem, using Access Points Page 18 of 77

20 3.2 emar Message Exchange Focus Areas Logistics Chains Management Components The main objective of Logistics Chains in the logistics Ecosystem is the utilization of Common Framework messages. The specific framework provides a well defined structure by describing standard roles and interactions in the logistic chain. It can be also used to structure business applications, allowing the emar Ecosystem to build upon the results of previous developments, and design shared knowledge on the base of well established logistic models. Some of the main messages of common framework are the Transport Service Description (TSD), Transport Execution Plan (TEP) or GS1 Booking, Transportation Status (TS), Goods Item Itinerary (GII), Multimodal e Waybill (MWB). In order to present a definition for each of the above messages we should first introduce the main roles involved in the logistics chain: Transport User (TU): Represents the person that needs to have cargo transported. He also provides the Transport Service Provider with instructions and detailed information about the transport items to be transported. Transport Service Provider (TSP): Responsible to ensures the transport of the cargo from the origin to the destination. Specifically TSP provides management of the transport services and the operation of the transport means and handling equipment. He provides also other administrative services required for moving the cargo. Transport Network Manager (TNM): Responsible for extracting all information available regarding the infrastructure (static or dynamic) related to planning and executing transport and makes this information available to the Transport User and the Transport Service Provider. Planning includes the advertisement of services from TSP to TU in a common format in terms of a schedule and a freight rate. Execution is the management of physical transport of the goods which includes exchanging information on the status of the shipment with the TU and the status of the transport infrastructure with TNM. Transport Regulator: Responsible for receiving all mandatory reporting (and checks if reporting has been carried out) in order to ensure that all transport services are completed according to existing rules and regulations. Below is the definition for the messages listed above: Transport Service Description (TSD): The document is sent from Transportation Network Manager to Transport Service Provider giving a status on the transport operation. Transport Execution Plan (TEP): The document is used in the negotiation of a transport service between a transport user and a transport service provider. Transportation Status (TS): A message to report the transport status and/or change in the transport status (i.e. event) between agreed parties. Page 19 of 77

21 Goods Item Itinerary (GII): Sent from TNM to TSP giving a status on the transport operation and the routes will be followed. Multimodal e waybill (MWB): Issued by the party who acts as an agent for the carrier or other agents, to the party who gives instructions for the transportation services (shipper, consignor, etc.) stating the details of the transportation, charges, and terms and conditions under which the transportation service is provided. Table 3.1: Message exchange areas for logistics chain Area emar Message description Related developments emar services Opti modal planning Data model on information to be supplied by ship to port/terminal system responsible for terminal and hinterland operation Linked to extended gateway concept/ practices Possible link with TEP and TS Extended services for optimized hinterland services Ship loading ebol to be linked to waybill of e Freight and industry developments from FIATA Ship Operation In close co operation with e Navigation and S100 standard, e Navigation is an International Maritime Organization (IMO) led concept based on the harmonization of marine navigation systems and supporting shore services driven by user needs. Table 3.2: Message exchange areas for ship operations Area emar Message description Related developments emar services Shipping Service descriptions Use and test Transport Service Description from e Freight A universal distributed directory of shipping services Page 20 of 77

22 Ship Voyage Monitoring Noon report Standard data model for ship monitoring particularly addressing environmental issues IMO Energy Efficiency Operational Indicator (EEOI) Also outputs from Flagship SVM service for onboard use and office use Global ship status database Ship voyage optimization services Statement of Fact Standard data model for communicating statement of fact information handled normally by ship agents Log management service with data quality checks and distribution management e Recruitment Standard data model for CVs in line with STCW Posting and viewing information about vacancies and job applicants Class Exchange Planned maintenance data model interfacing with Classification portals Benchmarking of shipping services Standard data model for shipping service benchmarking Service to be hosted by association or EU agency Page 21 of 77

23 3.2.3 Port Operation Port Operations consist of the exchange of commercial and logistic messages between port associated companies and between the public and private sector. It contains also the provision of information about vessels to the authorities. Table 3.3: Port reporting messages Port costs services and restrictions Port Clearance including SSN notifications Data model Maritime Single Window based on CRS Integrated information services Building blocks 3.3 Challenges to e Maritime Message Exchange Challenges considered by the emar project for the end to end transfer of messages within the supply chain include; Supply chain stakeholders do not have the same level or maturity of ITC infrastructures. It is unlikely that any one method for the transfer of messages will suffice as a practical solution in the near term. Some institutions do not have common guidelines for all the employees to enable them to handle changes in their working procedures. Human factors can also make some incompatibilities within the system. Very often there needs to be human intervention to gain approval to move through the loading and discharging processes. These steps can be difficult to change / improve. There may be additional process steps at individual ports that are non standard and require consideration. Other problems in message exchange: Some documents contain duplicated records/data. Different authorities may have to be provided with the duplicates of the same documents. Delays in the processing of electronic information can have a direct effect on delays in cargo handling. As a result of these challenges to an integrated e messaging solution within a defined Maritime community, it has been decided to utilize both Access Points and standard connectivity models in order to maximize the potential uptake by the different Maritime stakeholders. Page 22 of 77

24 3.4 emar Connectivity Services emar connectivity services can be established using different tools that produce services which can be used by Ecosystem participants to produce their own solutions. The emphasis in emar will be to connect or provide small apps with high level of robustness and usability addressing the needs of Maritime SMEs and close functionality gaps to promote integration for Maritime services in the EU transport system as specified in D1.1 to D1.3 of the emar project. Connectivity services in emar will support different groups of stakeholders in the following three approaches: Compose Integrate Collaborate Regarding the compose approach, will enable the connectivity between emar Ecosystem and platform and existing applications. The integrate approach support the collection of information from different sources and share them across the e Maritime applications. The third approach will help out the users of emar Ecosystem to collaborate via the supported emar applications. 3.5 emar Connectivity Standard Models The connectivity models consist of primarily existing technologies and standards which are widely used for systems communication. The fact will enforce the emar Ecosystem and platform to provide the required security levels and will enable also the different stakeholders group for collaboration. The most important connectivity models which are used in business domain are described below Representational State Transfer (REST) REST describes a lightweight way for establishing communication between different types of systems. It uses the HTTP request to post data and thus can also use all the supported operations which the specific protocol provides (Create, Read, Update, and Delete). In the REST architectural style, data and functionality are considered resources and are accessed using Uniform Resource Identifiers (URIs), typically on the Web. Restful solutions are very simple types of connectivity models and moreover are fully featured including security levels via secure sockets. Page 23 of 77

25 3.5.2 Simple Object Access Protocol (SOAP) As the REST, SOAP is lightweight way of communication that is independent from platform, transport or operating system. There are two types of SOAP requests. The first is the Remote Procedure Call (RPC) style request similar to other distributed architectures. This is usually synchronous; the client sends a message and waits to get a response or fault message back from the server. The second type of SOAP request is the document request. In this case, a full XML document is passed to/from the client and server, inside a SOAP message. SOAP is not as simple as REST. Usually a good analogy that is used to compare these two types is the example of mailing a letter. With SOAP an envelope is used, but with REST just a postcard, which is easier to handle, waste less paper and have less content Web Service Description Language (WSDL) The mechanics of the message exchange are documented in a Web Service Description (WSD). The WSD is a machine process able specification of the Web service's interface, written in Web Service Description Language (WSDL). It defines the message formats, data types, transport protocols, and transport serialization formats that should be used between the requester agent and the provider agent. It also specifies one or more network locations at which a provider agent can be invoked, and may provide some information about the message exchange pattern that is expected. In essence, the service description represents an agreement governing the mechanics of interacting with that web service. While the service description represents a contract governing the mechanics of interacting with a particular service, the web service semantics represent a contract governing the meaning and purpose of that interaction. The dividing line between these two is not necessarily rigid. As more semantically rich languages are used to describe the mechanics of the interaction, more of the essential information may migrate from the informal semantics to the service description. As this migration occurs, more of the work required to achieve successful interaction can be automated. Page 24 of 77

26 4 emar Access Points 4.1 Overview Access Points (APs) enable emar Ecosystem users to communicate each other in a secure and reliable way using electronic messages. In the emar Ecosystem, APs are the main entry points and provide controlled access to software services. Access Points can be considered as a gateway or bridge between the emar Ecosystem members. The way access points operates represents the concept of in which the user simply creates a message from relevant data, enters the destination address and presses send. The fact that no central platform is required and with the adoption of a public key infrastructure, access points addresses also the three important issues arising from electronic information exchanged: Security, Quality and Reliability and Ownership of Information. Access Points hold a major role to the establishment of a scalable, secure and efficient connectivity infrastructure. The main advantage arises by the adoption of Access Points is that it can be utilized from a large number of participants in the European Maritime Community. The above capabilities together with the efficient discovery functions provide the means to stakeholders to enter and quickly become part of the Ecosystem without the need to rely on point to point connections in order to establish the supported comprehensive set of Maritime Logistics Services. Access Points can be considered as the transport infrastructure for Logistics Ecosystem by providing a standard set of information types which Common Framework supports as mentioned in the previous section. The communication protocol and the implementation of Access Points has been highly influenced and is largely compatible with the European Standard implementation of Pan European Public Procurement Online (PEPPOL) project Access Points and also comply with the Business Document Exchange Network standard (BUSDOX). BUSDOX is document agnostic, meaning participants can transfer ANY kind of electronic document between ANY network. The main difference between BUSDOX and other document exchange systems is that BUSDOX is designed to support what is known as a 4 corner model. The 4 corner refers to the fact that the trading participants (such as buyer and seller) may exchange their documents via two (or more) intermediary service providers. An important advantage of this approach is that it gives the possibility to participants to access the network using their own Access Points provider and have immediate connectivity with all other participants on the network. 4.2 Exchange Security: Security and integrity of the messages exchange through the Ecosystem Transport Infrastructure relies on using a Public Key Infrastructure (PKI) to establish a trusted network. When Access Point or Service Metadata Provider (SMP) providers sign the Ecosystem Transport Infrastructure Agreement they receive a Digital Certificate. This certificate contains the key information for validating their communications on the network. Page 25 of 77

27 This allowing a reviever of a message to confirm the identification of the sender and ensures that the message has not been modified in transit. In summary, it ensures tnat only known and trusted providers have access to the Transport Infrastructure. 4.3 Quality and Reliability The BUSDOX communication specifications (LIME for the communication between the participants and the Access Points; START for the communication between APs).are used to ensure the quality of the information and the quality and reliability of the communication channels Lightweight Message Exchange Profile (LIME) The Lightweight Message Exchange Profile (LIME) is an optimal solution for small and medium Enterprises (SMEs) to access BUSDOX infrastructure from the economic and the performance point of view. This is because the establishment of a communication using the LIME does not require hosting online endpoints; hence no firewall crossing and no server infrastructure. Additionally there are no requirements for supporting advanced WS * standards such as WS Trust, WS Reliable Messaging. Additionally only minimal requirements are necessary to support WS Security (authentication headers only). The main advantage of the Lightweight Message Exchange Profile is that it allows different systems to participate in the BUSDOX infrastructure without needing to access service metadata or host an Access Point. Instead, they rely on an Internet Service Provider (ISP) to provide LIME services to them. A simple analogy is Internet Large companies may run their own Simple Mail Transport Protocol (SMTP) server and proprietary clients to create and read messages, but individuals or small companies rely on an ISP to provide an SMTP Relay and POP3 or IMAP server. A summary of benefits that LIME brings to the emar solution include: It provides access over a simple HTTPS protected channel. It utilizes existing standards where appropriate. It lowers the cost of entry for SME s and individuals Secure Trusted Asynchronous Reliable Transport (START) BUSDOX infrastructure is created through the communication of Access Points in a peer to peer model across the internet. The requirements for the form of the specific infrastructure and for the communication to take place are that each AP should know the endpoint address of others AP. This can be achieved with the use of BUSDOX Service Metadata Publishing Infrastructure [3] which enables the exchange of digital certificates and endpoint URLs and therefore automates the inclusion of new or modified APs. Such an exchange is achieved by holding the actual metadata information for a given participant identifier and document type combination. Moreover AP may communicate via optional Transport Profiles, but they must always offer a START endpoint by which any other AP may communicate. Page 26 of 77

28 B.1.1 Advantages of START The goal of START is to support the message exchange between two or more ends, in a reliable and secure way using web services [7]. The profile is designed to: Enable the different implementers to build and therefore to gain access to BUSDOX with no further requirements or adjustments to implement other transport profiles. Provide detail description of the transport level requirements in a single document. Provide an efficient and interoperable communications pattern that APs can use to communicate very easy. Define the message exchange formats and patterns clearly. Guarantee that AP uses a secure transport protocol and thus the messages are reliably delivered between APs. This also includes provision of prerequisites for logging and proof of delivery for messages at the transport level. Guarantee confidentiality of exchange messages using transport level encryption. Guarantee integrity and authenticity of received messages using digital signatures and validation of these signatures. Support transfer of messages that are opaque to the Access Point Provide different formats of headers within the message envelope so Access Points can forward/transfer messages without requiring access to the business message. Provide a standard message for the authentication events in BUSDOX infrastructure in the form of SAML 2.0 assertions / tokens. Recipients can assume that senders have been authenticated by their token Issuers and obtain further proof via cryptographically signed tokens. More details for the above definitions are given in Page 27 of 77

29 Appendix B emar Access Points sections 4 and Ownership of Information APs are independent from the traditional approach where the exchange of data involves multiple isolated systems. APs follow an entity centric approach that achieves the exchange of all the digital data in the Technology Ecosystem to be directly managed by each single resource (AP). A participating organization registers to an Access Point and via this; it is possible to exchange information all the other participants in the ecosystem. More details about the APs are provided in the Appendix B for the interested reader. Page 28 of 77

30 5. The emar API Library In emar the principal objective of API s is to facilitate the creation of an upgraded and low cost connectivity infrastructure through the provision of efficient and quality shipping services fully integrated in the overall European transport system. Additionally, emar API s will support the Service Oriented Architecture (SOA) which is one of emar main targets in order to provide the ability for automated application lifecycle management. emar API s comprised of four main categories and which are described in details in the next sections: 1. Port Operations 2. Ship Operations 3. Transport Logistics 4. Third Party Digital Services The emar API Template includes the following: 1. Methods : The supported methods of API 2. Connectivity Protocol: The types of connectivity protocols are used to support the methods 3. Parameters (input, output): Details of all the input and output parameters along with description of values that can be passed. 4. Description: Detailed description of the API and methods Each method of the API includes the following tables: Parameters Response Table 5.1: Method Parameters Parameter Name Type Description Required parameters Required Parameter Type of parameter Detailed description of required parameter Name Optional parameters Optional Parameter Type of parameter Detailed description of optional parameter Name Table 5.2: Method Reponse Response Name Name of the response Type Type parameter of Description Detailed Description of response Page 29 of 77

31 Errors Return Value 5.1 Port Operations Table 5.3: Method Response Errors Error Code Error Type User Message The code of the error displayed Type of Error The message displayed on user s on user s applications. application Table 5.4: Method Return Values Field Name Error Type User Message Description of field Type of field Description of the field The diagram in Figure 5.1 gives an overall description regarding the port operations which will be included in emar Ecosystem and Platform. Figure 5.1: Port Operations in emar Ecosystem As indicated in Figure 5.1 the most important system which is widely used in most of EU ports today is the Port Community System (PCS) and thus the main goal is the provision of some services from the particular system. The main operation of PCS is to support the exchange of commercial and logistic messages in a port environment on a business level. PCS are also closely related to Port Single Windows which are used for providing information about the vessel to the authorities on a port level, B2A (Business to Administration). Page 30 of 77

32 5.1.1 emar API for Port Community Systems (PCS) The API for Port Community Systems can play a major role in facilitating the more efficient movement of goods while allowing Customs and other government departments to maintain effective controls. Such API s can also have a significant contribution as Europe moves towards the Single Window concept. The stakeholder groups which can use the API consist of private companies on the one hand (shipping agents, terminal operators, forwarders, Customs brokers, etc.) and of public or government agencies (Customs or Port Authorities) on the other hand. Moreover, in terms of the client structure, shipping lines and freight forwarders play the most important role, followed by importers and exporters in general or Customs and shipping agents. In this way the API will form a cost effective connectivity infrastructure through the emar Ecosystem which will enable a number of ports to connect and hence to create an efficient collaboration between the key authorities and stakeholders. The emar API for Port Community Systems (PCS) provides different login/administration services and terminal instruction services. The provided services consist of the submission of different electronic documents and information offering the guarantee of a secure and reliable storage solution. Additionally, it provides the ability to search electronic documents on specific fields. A more detail description of the provided services is mentioned in the next sections. The table below lists the supported operations by Login and Administration Services. For a more comprehensive description see section 0. Table 5.5: PCS Operations for Login and Administration Services Method Connectivity Protocol Log In 1. REST / Get 2. WSDL Check 1. REST / Session Get 2. WSDL Change Password 1. REST / Get 2. WSDL Input and Output See section 0 See section A.1.2 See section A.1.3 Description Initiate a session in PCS and enables the interaction with Terminal Instruction Services. Allows the user to verify that the initiated session is still active. Allows the user to change the current password which holds with a new one. Page 31 of 77

33 Login and Administration Services The Login and administration services can provide additional security mechanisms of identity and access management. Using these mechanisms the API can verify that a user is the entity that it claims to be, and also for determining which actions an authenticated principal is allowed to perform. This will ensure the continued operation of the provided services. Also the particular services are prerequisite in order for the user to be able to interact with Terminal Instruction Services. The provision of such operation in the API will lead to a secure connectivity infrastructure which will support an improved information exchange between Administrations and business (A2B & B2A) under the emar Ecosystem and Platform Terminal Instruction Services The Terminal Instruction Services allows shipping agents to send the vessel loading and discharge lists to the container terminals and obtain the appropriate confirmations or feedback for the submission of those lists. The main benefits of terminal instruction services are: Provides the possibility for integration with all the container terminals Ability to produce any document separately Ability to capture the customs information and obtain information on customs declarations to compile cargo manifest. Ability to provide tracking and tracing information to all parties involved Increased control of the information and documentation processed and reduction in errors. The terminal instruction services through trusted protocols ensure the appropriate information is received only by those that need it, when they need it. The reliable connection increase also levels of automation in information exchanges between different stakeholders which will set the foundations for cooperative networking strategies through the emar Ecosystem. The table below lists the supported operations by Terminal Instructions Services. For a more comprehensive description see section A2. Table 5.6: PCS opearations for terminal instruction services Method Get TVA Model Equipment Search Equipment Save Equipment List Document Connecti vity Protocol Input and Output Description WSDL See section 0 Allows the users to get the TVA model for each of equipment that satisfies a set of parameters. WSDL See section A.2.2 Allows the users to search for equipment from the relevant pool based on specific criteria. WSDL See section A.2.3 Send equipment list to the PCS of emar Ecosystem. Page 32 of 77

34 5.2 Transport Logistics The diagram in Figure 5.2 gives an overall description regarding the transport logistics operations which will be included in emar Ecosystem and Platform Figure 5.2: Transport Logistics Operations in emar Ecosystem The main applications which will be included in emar Ecosystem and platform regarding the provision of transport and logistics includes: 1. Multimodal Corridor Design and Monitoring applications: Addresses terminal or transport leg related infrastructure for transport (capacity, transfer systems etc), operational rules thresholds and monitoring systems. 2. Intermodal Transport Chain Planning: Using both static (infrastructure) as well as dynamic (operational) characteristics, the application addresses the transport booking and planning of a transport chain. 3. Chain Monitoring & Control: Addresses monitoring of transport and load units on an even driven basis by receiving status data from service providers as well as sensing systems. 4. Performance management and benchmarking: Provide various types of services to different stakeholders group such as cargo owners, service providers, freight integrators, public authorities, and national and EU agencies in order to increase the transparency. 5. Loading planning and optimization: Capable to communicate with port and cargo monitoring systems. 6. Voyage management systems: Manage contract reviews, appointment for agents, operational supplies, voyage instructions to Masters, compliance management and completion activities Page 33 of 77

35 5.2.1 emar API for Transport and Logistics The optimization process in transport and logistics domain plays a major role. Research has shown that a 5 percent reduction in transportation cost has the same profit and loss impact as a 30 percent increase in sales. Not only companies get sustained cost savings, logistics improvements generally lead to increased service levels as well. The API for transport and logistics will create a connectivity infrastructure, capable to contribute to the optimization process and hence to lead to a cost reduction and increased of profitability Tracking & Tracing Service The objective of a container tracking service is to collect more information during a supply chain process including shipments in connection with mobile business. The emar Ecosystem and platform will provide through that service, continues connectivity and keep the involved stakeholders up to date regarding the exact situation and position of goods transported or in storage. Particularly the tracking and tracing service enables a client application to learn information of the progress of a multimodal transport for a specific consignment and container. By provining the container and consignment unique identifiers, the service will provide the latest status report of the specific consignment and container (e.g. arrival/ departure in terminals along the transport, loading/ unloading activities of the related container e.t.c). The response message is based on the Transportation Status message (TS) exported from efreight. For more information see section The table below lists the supported operations provided by emar Ecosystem regarding Transport and Logistics. For a detail description see section 0 Table 5.7: Operations for Transport Logistics Method Tracking Tracing Connectivity Protocol Input and Output Description WSDL See section A.3 Provide the latest status report of a specific consignment and/or container (e.g. arrival/ departure in terminals along the transport, loading/ unloading activities. Page 34 of 77

36 5.3 Third Party Digital Services The main objective of emar for third party digital services is to integrate digital products of various information providers in the emar software platform so they can be readily used by port, shipping, or logistics applications or in developing composite applications for use by specific user communities. They also aim to support the Maritime sector by providing a connectivity infrastructure through the emar Ecosystem and platform which will automate time consuming procedures and reduce man effort and costs emar API for erecruitment The Maritime erecruitment service, implemented over the emar Ecosystem, aims to become an assisting service to future or existing crewing applications by consolidating Recruitment Requests RRs as inputs, as well as Candidate Crew Applications CCAs. Maritime erecruitment facilitates the procedure of matching the Recruitment Request to the Candidate Crew Application which satisfies the recruitment criteria. The figure 14 below shows the relationship between the crew management part of an application and Maritime erecruitment. Furthermore users of Maritime erecruitment have the ability to exchange different messages via emar Access Points. The provision of recruitment services will form a scalable connectivity infrastructure between the managers and candidates which will create a competitive environment in the Maritime domain and gives a lot of motivation for recruitment on the specific area. The table below lists the supported operations provided by emar Ecosystem regarding erecruitment. For a more comprehensive description see sections 0 Table 5.8: Operations for erecruitment Method Connectivity Protocol Find CCAs WSDL / Access Points Find RRs WSDL / Access Points Input and Output Description See section 0 Allows different stakeholder s groups (Shipping Managers, Shipping Agents) to full fill a recruitment request with particular criteria such as Nationality, Age, and qualifications. Then the matching formula takes the request as an input, and through some calculations returns the matching results. See section 0 Has the similar purpose as the above except that the user submits a CCA and in order to get as a result a list with the matched RRs Page 35 of 77

37 STCW Overtime Budget Crewing reference model Crew Information Fleet Schedule Crew planning Recruitment Request Recruitment Recruitment reports Recruitment Status Leave request Appraisals Crew Schedule Career Development RR RRs e-crewing Crew Competence Chart Training plan -records SLA CCAs CCA CCA Remuneration Salary / Bonus/ Overtime Figure 5.3: emar erecruitment as part of Crew Management emar API for Maritime Financials The API for Maritime Financials support a wide range of financial functionalities required for monitoring and controlling all the financial actions perform by any shipping company. Some of the main features that the API supports are: Multi Company Multi Group Multi Currency Open Items Voyage Accounting Dynamic Chart of Accounts Cash Flow analysis Moreover the particular API enables the creation of a connectivity infrastructure between a shipping company and its clients for performing different accounting transactions. The reliable and cost effective communication will improve also the collaboration of the different stakeholder groups. The table below lists the supported operations provided by emar Ecosystem regarding Maritime Financials. For a more comprehensive description see sections A.5. Page 36 of 77

38 Method Marine Accounting and M.I.S Budgeting System Payments Module Connectivity Protocol WSDL / Access Points WSDL / Access Points WSDL / Access Points Table 5.9: Operations for Maritime Financials Input and Output Description See section 0 Designed for multi Company, multi Group, multi Currency Accounting support. Support of Voyage Accounting and Analysis, Running Cost Reporting, Cash Flow Analysis including accruals. Suitable for Ship management, Ship owning, Ship holding Groups, Operators, Agents, Bunker Traders, etc. See section A.5.2 Specially designed for the Accounting department of a Shipping company. Designed to support all types of calculations and the user can budget: Running Costs, Income, Profit, Financing Costs, Credit Line, Voyage Budgeting, etc. See section A.5.3 Specially designed for Accounting Department. Selection of Outstanding Payables due in certain period. Supports partial payments, on account payments and bank transfers. Selection of Invoices, Prepayments and Credit Notes to be included at a certain remittance Page 37 of 77

39 5.4 Ship Operations The diagram in 413 gives an overall description regarding the ship operations which will be included in emar Ecosystem and Platform. Figure 5.4: Ship Operations in emar Ecosystem The main goal is the provision of several services, compatible with the emar SOA and also for covering each area of shipping domain. The basic modules of the emar shipping operations include: 1. Strategic Fleet Management: Emphasizes on traditional strategies such as market segment focus, fleet scheduling and business networking including cooperative planning of resources. Significant attention will be given on Green Shipping strategies such as monitoring CO2 operational index. 2. Personnel management and training systems: Manage setting terms of employment for seagoing personnel. Co ordinates also the recruitment process and assigning crews to a company s vessels. 3. Chartering: Manage and monitoring the chartering rates and trends from brokers, brokers reports, communication between charterers and vessels, and alerting company to possible problems. 4. Ship condition monitoring, maintenance and emergency support systems: Controls and monitoring the efficiency of the ship by generating the appropriated reports. Also performs surveys management to support Class in identifying areas of concern upon which planned surveys should concentrate, alert services on what has to be done and information on 'what has changed since specific dates. Also is capable to provide a standard level of intelligent services to self organize following deployment or failure and co ordination of remote operations. Page 38 of 77

40 5.4.1 emar API for Ship Operations The following requirements are derived from analysis of the operation to be modeled by MJC² in the T2.4 Simulation & Optimization task. (Note that other partners in this task may suggest additional requirements this initial summary is based on MJC²'s work only.) The emar Optimization & Simulation (EOS) system built by MJC² will address integrated logistics optimization for container operations, focusing on the interactions between modes (ship, truck, rail) that take place in the port. The EOS will be designed to make use of information about the ship, including its location and cargo, for logistics optimization and simulation purposes. The following sections outline the data elements that will be required to be part of the EMSF. This document is not intended to be a detailed specification but simply outlines the type of information required. As the T2.4 work progresses these requirements will be refined and additional requirements may emerge. The table below lists the supported operations provided by emar Ecosystem regarding Ship Operations. For more information see sections A.6. Table 5.10: Operations for Ship Operations Method Connectivity Protocol Ship Status WSDL / Access Points Voyage WSDL / Information Access Points Cargo Details WSDL / Access Points Input and Output See section 0 Description Provide optimizations regarding the current status of a ship. See section A.6.2 Provide different optimizations Information regarding ship voyage. See section A.6.30 Provide different optimizations Information regarding cargo Page 39 of 77

41 6 Conclusion The emar connectivity architecture facilitates the interfacing of different Maritime services with emar Ecosystem in a secure, flexible, reliable and low cost way using Access Points. The implementation of the connectivity architecture aims to increase the collaboration of maritime stakeholders in both private and public parties and facilities the development of the next generation of emaritime infrastructure, applications and services. The provided APIs from emar Ecosystem (Appendix A) cover a wide range of business users by offering a broad range of typical emaritime services such as security, shipping, port operations, and transport logistics. Additionally, the emar APIs offer both dedicated and customisable services since use varies over time and a large number of stakeholders use them for different purposes. Thus, this deliverable offers an upgraded connectivity and information management solution that will promote coherent, transparent, efficient and simplified solutions in support of cooperation, interoperability and consistency between member States, sectors, business and systems involved in the European Maritime Transport System. Page 40 of 77

42 7 References 1. Katsoulakos, T., Katsoulacos, Y Integrating corporate responsibility principles and stakeholder approaches into mainstream strategy: a stakeholder oriented and integrative strategic management framework. Corporate Governance. Vol. 7 Iss: 4. pp Spohrer, J., Maglio, P., Bailey, J., Gruhl, D Steps Toward a Science of Service Systems. Computer, 40:1, pp Fremantle P Secure Trusted Asynchronous Reliable Transport (START) 4. Sylvest G Service Metadata Publishing (PEPPOL). 5. Fremantle P Lightweight Message Exchange Profile (LIME). 6. Papazoglou, M.P., Traverso, P., Dustdar, S., Leymann, F Service oriented computing: State of the art and research challenges. IEEE Computer 40(11), Lambrou, M.A., Rødseth, Ø.J., Foster, H., Fjørtoft, K Service oriented computing and model driven development as enablers of port information systems: an integrated view. WMU Journal of Maritime Affairs, Volume12, Issue 1, pp Allen, P SOA Governance: Challenge or Opportunity? SOA Best Practice Report, CBDI Forum summary.php3?page=/secure/interact/ /challenge_opportunity.php&area=silver. 9. Chesbrough, H. and Spohrer, J A research manifesto for services science. Communications of the ACM, 49:7, pp Dini P. and Nicolai A The Digital Business Ecosystem. FP6 IST e Business Integrated Project. 12. Liang Jie Zhang, Jia Zhang, Hong Cai Services Computing, Tsinghua University Press, Beijing and Springer Verlag GmbH Berlin Heidelberg. Page 41 of 77

43 Appendix A emar API Library The section contains a comprehensive description for each of the supported operations provided under emar APIs. In general each of the following tables is an abstract representation of a parameter s characteristics and relationship to other parameters. Additionally every other system in the Maritime sector needs to use the provided services from emar Ecosystem should comply with the below structures. Login and Administration Services Login Parameters The table below lists the required and optional parameters that this operation support. Response Table A.1.1: Login Parameters Parameter Name Type Description Required parameters User Login text Username of the registered user in the PCS. Password text The password that the user has introduced in User Login Optional parameters Organization Code (optional) text A Unique code related with user/ organization The table below describes the response that returns in a successful operation call. Table A.1.2: Login Response Response Name Session Ticket see section Return Value Errors Type text/xml Description A serialized data set that contains all the information about the user and its company registered in PCS. The most relevant field of this structure is the Ticket GUID that identifies the session in use. The table below identifies error messages that the API could return in response to a call to this method. Page 42 of 77

44 Table A.1.3: Login Response Errors Error Error Type Code 1 Authentication failed 2 Required field missing 3 Required field missing User Message Authentication is not valid because login information is incorrect or the user you are trying to access does not exist or the user's organization is inactive. Missing parameter: User Login Missing parameter: Password Return Value The table below describes each field of the return value for the specific operation Page 43 of 77 Table A.1.4: Login Return Value Field Name Type Description Ticket GUID User Name text The unique name of user in the emar Ecosystem PCS. Organization text An extra code related with user s organization Name Address text Address Postal Code text The postal code of user Location Code text The location ISO code of user Country Code text The country ISO code of user Phone Number The phone number of user Fax Number The Fax number of user text The address of user Profile Code text The associated profile code for the user Culture Code text The associated culture code for the user Last Update Date Time The date of the last valid update has been made from user Host Address text The host ID portion of an IP address related with user. Password text The unique password of user in the emar Ecosystem PCS. User Session text A unique number associated with user session in the emar Ecosystem. User Profiles User Login text Name of the registered user in emar Ecosystem PCS Organization text An extra code related with user s organization Code Profile Code text The associated profile code for the user Culture Code text The associated culture code for the user User Actions

45 User Login text Name of the registered user in emar Ecosystem PCS Organization text An extra code related with user s organization Code Profile Code text The associated profile code for the user Culture Code text The associated culture code for the user Service Code text The code of the service requested by user Role Code text The code of the role which user holds in the emar Ecosystem PCS Action Code text The code of the actions selected from users. Organization Roles Organization text An extra code related with user s organization Code Role Code text The code of the role which user holds in the PCS Service Code text The code of the service requested by user Service Role text The role of the service in the PCS. Check Session Parameters The table below lists the required and optional parameters that this operation supports. Table A.1.5: Check Session Parameters Parameter Type Description Name Required parameters Session Ticket text The user session field of Ticket GUID as described in section Return Value Response The table below describes the response that returns in a successful operation call. Table A.1.6: Check Session Response Response Name Type Description Session Ticket See section text/xml In the case of valid session, the result of the method will be the same of the one got it by means of Login method. Return Value Errors Page 44 of 77

46 The table below identifies error messages that the API could return in response to a call to this method. Table A.1.7: Check Session Response Error Error Error Type User Message Code 1 Required field missing Missing parameter: Session Ticket 2 Not Found User Session is not valid or session expired Return Value See return value in Return Value section in A1.1. Change Password Parameters The table below lists the required and optional parameters that this operation supports. Table A.1.8: Change Password Parameters Parameter Type Description Name Required parameters Session Ticket text The user session field of Ticket GUID as described in section Return Value Old Password text The current password of user New Password text The new password of the user to be replaced Response The table below describes the response that returns in a successful operation call. Table A.1.9: Change Password Response Response Name Change Errors Type Boolean True/false Description Operation successfully completed and password has changed. The table below identifies error messages that the API could return in response to a call to this method. Page 45 of 77

47 Return Value True / False Terminal Instruction Services Get TVA Model Equipment Parameters Page 46 of 77 Table A.1.10: Change Password Response Errors Error Error Type User Message Code 1 Required field missing Missing parameter: Session Ticket 2 Required field missing Missing parameter: Old Password 3 Required field missing Missing parameter: New Password 4 Not Valid The selected new password is not valid 5 Not Found User Session is not valid or session expired The table below lists the required and optional parameters that this operation supports. Response Table A.2.1: Get TVA Model Equipment Parameters Parameter Type Description Name Required parameters Call Reference text Code of the ship call. Shipping Line text Code of Shipping Line Terminal Code text Code of the terminal List Type text Type of the operation to be consulted (loading or unloading operations). Session Ticket text The user session field of Ticket GUID as described in section Return Value Optional parameters Agent Code text Code of the shipping agent which represents the shipping company that transport containers. The table below describes the response that returns in a successful operation call. Table A.2.2: Get TVA Model Equipment Response Response Type Description Name TVA Data text/xml The TVA model for each of equipments which match the values of

48 the above fields. See section Return Value Errors The table below identifies error messages that the API could return in response to a call to this method Table A.2.3: Get TVA Model Equipment Response Errors Error Error Type User Message Code 1 Required field missing Missing parameter: Call Reference 2 Required field missing Missing parameter: Shipping Line 3 Required field missing Missing parameter: Terminal Code 4 Required field missing Missing parameter: List Type 5 Required field missing Missing parameter: List Type 5 Not Found User Session is not valid or session expired Page 47 of 77

49 Return Value The table below describes each field of the return value for the specific operation Table A.2.4: Get TVA Model Equipment Return Value Field Name Type Description TVA Annex 2 Actual Time Date The actual arrival time Time Authorization Date Date The date which has been authorized Time Call Reference text Code of the ship call Estimate Time Date The estimate arrival time Arrival Time Summary text Declaration Summury Declaration Terminal Address text Address of terminal Terminal CIF text Code of CIF Terminal Terminal City text City where the terminal is. Terminal Name text Name of the terminal Terminal PO BOX text Post office Box of terminal for receiving transport documents Total Containers text Number of containers that comply with the input parameters Vessel Name text Name of the ship Voyage Number Number Number assigned to a round trip sea voyage TVA Report (For each Container) Port Of Loading text Name of Loading Port for the container Port of Departure text Name of Departure Port for the container Equipment Type text Type code of equipment Container Code text Container ISO Code Page 48 of 77

50 Search Equipment Parameters The table below lists the required and optional parameters that this operation supports. If one of the optional values is empty the search engine does not filter based on that field. Table A.2.5: Search Equipments Parameters Parameter Name Type Description Required parameters Vessel Port Call text Call number assigned to the ship Container Number text Container ISO Code Session Ticket text The user session field of Ticket GUID as described in section Return Value Optional parameters Vessel Agent text Code of the shipping agent (which issue the load/unload order) Carrier Agent text Code of the consignee (which represents the shipping company that transport containers). Operation Type text Type of the operation to be consulted (loading or unloading operations). Terminal Agent text Code of the port terminal that will carry out operations Status text Type of movement. Valid inputs: Export, Import, Trans shipments and Removal. Full or Empty text Searching full or empty containers. Valid Inputs: Full, Empty Response The table below describes the response that returns in a successful operation call. Table A.2.6: Search Equipments Response Response Name Search Equipment Errors Type text/xml Description Contains all the relevant information regarding the equipments, satisfy the values of the above fields. See section Return Value The table below identifies error messages that the API could return in response to a call to this method. Page 49 of 77

51 Table A.2.7: Search Equipments Response Errors Error Error Type User Message Code 1 Required field missing Missing parameter: Vessel Port Call 2 Required field missing Missing parameter: Container Number 3 Required field missing Missing parameter: Session Ticket 4 Not Found User Session is not valid or session expired Return Value The table below describes each field of the return value for the specific operation Table A.2.8: Search Equipments Return Value Field Name Type Description Equipment Container Number Number Container ISO Code Vessel Port Call Ref. text Name of the port of call for the specific container. Vessel Name text Name of the ship Operation Type Code text Type code of operation (L / U) Operation Type Desc. text Description of Operation Type (Loading / Unloading) Equipment Type Code text Type code of equipment Equipment Type Desc. text Description of Equipment type (e.g. Dry Bulk Container) Full Empty Type Code Yes/No Indicator if the container is full or empty (Y/N) Full Empty Type Code Yes/No Description of the Full Empty indicator (Yes/ No) Desc. Equipment Status Type text Type code of equipment status Code Equipment Status Type text Description of equipment status type code Desc. Included Yes/No Indicator if the equipment is included or not in the container Confirmed Yes/No Indicator if the equipment is confirmed or not Cancelled Yes/No Indicator if the equipment is cancelled or not Vessel Agent Code text Code of the shipping agent Vessel Agent Name text Name of the shipping agent Carrier Agent Code text Code of the consignee Carrier Agent Name text Name of the consignee Page 50 of 77

52 Container Terminal text Terminal Code of container Shipping Line text Name or initials of shipping company Shipping Line text Description or full name of shipping company Description Execution Date Date Date of Execution Time Sender text Code of the sender Sender Name text Name of the sender Delivery Place Code text Code of delivery place Delivery Place Desc. text Full name of delivery place Next Prev. Load text Code of the next discharge port Discharge Port Code Next Prev. Load text Description of the next discharge port Discharge Port Description Summary Declaration text Summary for all goods brought into the customs territory Authorized Yes/No Indicator if the container is authorized or not Gross Weight Number Gross weight of container (Kg) Container Length Number Length of the container (feet s) Booking Number Number The Booking number Discharge Port Code text Code of the discharge port Save Equipment List Document Parameters The table below lists the required and optional parameters that this operation supports. Table A.2.9: Save Equipment List Document Parameters Parameter Name Type Description Required parameters Equipment List text/xml Contains information about Equipment. See Section Document Equipment List Document Session Ticket text The user session field of Ticket GUID as described in section Return Value Page 51 of 77

53 Response The table below describes the response that returns in a successful operation call. Errors Table A.2.10: Save Equipment List Document Response Response Type Description Name Send Results text/xml Gives the appropriate feedback to the user when he executes the specific action. The table below identifies error messages that the API could return in response to a call to this method. Table A.2.11: Save Equipment List Document Response Errors Error Error Type User Message Code 1 Required field missing Missing parameter: Session Ticket 2 Required field missing Missing parameter: Equipment List Document 3 Not Found User Session is not valid or session expired Equipment List Document The table below describes each field for the equipment list document. Table A.2.12: Save Equipment List Document Return Value Field Name Type Description Interchange Header Interchange Sender text Name of sender Interchange Recipient text Name of recipient Date And Time Of Preparation Date Of Preparation Date Date of document preparation Time Of Preparation Time Time of document preparation Message Header Message Reference Number text Reference number of document Message Identifier Message Type text Type of message Message Version Number Number Version of the document Message Release Number Number Release number of document Controlling Agency Code text Code of shipping agent Association Assigned Code text Code of the assigned association Page 52 of 77

54 Beginning Of Message Document Name Code text Code of document Document Name text Name of document Document Number Number Document unique number Message Function Code text Code of message function Response Type Code text Code of response type Date Time Period Date Or Time Or Period Date Function code qualifier Function Code Qualifier Time Date Or Time Or Period Value Date Value of date, time or period Time Date Or Time Or Period Date Format of date, time or period Format Code Time Transport Information Group Transport Stage Code text Code qualifier of transport stage Qualifier Transport Mode Name Code text Name of transport mode Carrier Identifier text Carrier unique code Carrier Name Name of carrier Transport Means text Unique name of transport means identification Identification Name Identifier Transport Means text Name of transport means identification Identification Name Code List Identification Code text Code of identification code lists Reference Code Qualifier text Code of reference qualifier Reference Identifier text Reference unique identifier Place Location Identification Location Function Code text Unique code of location function Qualifier Location Name Code text Code of location Location Name text Name of location Name And Address Party Function Code Qualifier text Unique code of party function Party Code Identifier text Code of party Name And Address text Name and address of party Description Equipment Details Group Equipment Type Code text Unique type code of equipment Qualifier Equipment Identifier text Unique identifier for equipment Page 53 of 77

55 Equipment Size And Type Equipment Size And Type Number Code of size and type of equipment Description Code Equipment Size And Type Number Description of size and type of equipment Description Equipment Status Code text Code of equipment status Full Or Empty Indicator Code Yes /No Indicator if is full or empty Measurements Measurement Purpose Code text Code of measurement purpose Qualifier Measured Attribute Code text Code of measured attribute Value Range Measurement Unit Code text Code of measurement unit Measurement Value Number Value of measurement Free Text Text Subject Code Qualifier text Code of text subject Free Text Value Code text Value of free text Page 54 of 77

56 Tracking & Tracing Services Parameters The table below lists the required and optional parameters that this operation supports. Table A.3.1: Tracking & Tracing Services Parameters Parameter Name Type Description Required parameters Consignment ID text The consignment ISO Code Optional parameters Container ID text The container ISO Code Response The table below describes the response that returns in a successful operation call. Table A.3.2: Tracking & Tracing Services Response Response Name Type Description Response Code text Transportation Status Complete Response Description text Descriptive result of the method called. Valid value: Status generated Transportation Status text/xm l The current status of transportation. See section Errors Return Value The table below identifies error messages that the API could return in response to a call to this method. Table A.3.3: Tracking & Tracing Services Response Errors Error Error Type User Message Code 1 Internal Error Service Exception 2 Not Found <container ID> not found for consignment CONS2 OR Consignment <consignment ID> not found 3 Required field missing Missing parameter: Consignment ID Page 55 of 77

57 Return Value The table below describes each field of the return value for the specific operation Page 56 of 77 Table A.3.4: Tracking & Tracing Services Return Value Field Name Type Description Search Results Transportation Status text Circulate reports of transportation status or changes in status (events) among a group of participants UBL Version ID text The earliest version of UBL Profile ID text User defined profile of the customization of UBL ID text An identifier for this document, assigned by the sender Carrier Assigned ID text A reference number assigned by a carrier or its agent to identify a specific shipment, such as a booking reference number when cargo space is reserved prior to loading UUID text A universally unique identifier for an instance of this document Issue Date Date The date, assigned by the sender, on which this document was issued Issue Time Time The time, assigned by the sender, at which this document was issued Name text Text, assigned by the sender that identifies this document to business users Description text A textual description of transportation status. Note text Free form text pertinent to this document, conveying information that is not contained explicitly in other structures. Shipping Order ID text A reference number for a shipping order Other Instructions text An instruction regarding this message Transportation Status Type Code text A code signifying the type of status provided in a Transportation Status document Transport Execution Status Code text A code signifying the overall status of transport service execution Consignment text A consignment associated with this Transportation Status report Transport Event text An event associated with this Transportation Status report Document Reference text A reference to another document associated with this document Signature text A signature applied to this document

58 Sender Party text The party sending this Transportation Status report Receiver Party text The party receiving this Transportation Status report Transportation Status Request text A reference to the Transportation Status Request Document Reference to which this report is a response. TEP Document Reference Updated Pickup Transport Event text A reference to the Transport Execution Plan associated with the transport service whose status is being reported Update of the original plan regarding a delivery Updated Delivery Transport text Event Status Location text Locations associated with this Transportation Status report Status Period text A period for which status is provided emar erecruitment Find Candidates Crew Applications Parameters The table below lists the required and optional parameters that this operation supports. Response Table A.4.1: Find Candidates Crew Applications Parameters Parameter Name Type Description Required parameters Recruitment Request text Contains different information regarding a request for recruitment. See section Return Value The table below describes the response that returns in a successful operation call Table A.4.2: Find Candidates Crew Applications Response Response Name Type Description Candidate Crew Application text Contains different information regarding curriculum List vitae. See Section Page 57 of 77

59 Errors The table below identifies error messages that the API could return in response to a call to this method Table A.4.3: Find Candidates Crew Applications Response Errors Error Error Type User Message Code 1 Internal Error Service Exception 2 Required field missing Missing parameter: RR details Return Value The table below describes each field of the return values for the specific operation Table A.4.4: Find Candidates Crew Applications Return Value Field Name Type Description Candidate General Information CCA ID text The date, assigned by the user, on which this request was issued Family Name Date The start date of request Time First Name text Candidate first name Date Of Birth Date Candidate date of birth Place Of Birth text Candidate place of birth Home Address text Candidate home address Telephone text Candidate telephone Date Of Submission Date Date of submission by candidate Next Of Kin First Name text Candidate closest living blood relative first name Next Of Kin Last Name text Candidate closest living blood relative last name Next Of Kin Home Address text Candidate closest living blood relative home address Next Of Kin Telephone text Candidate closest living blood relative telephone Dependants Number Candidate number of dependants Sons Number Candidate number of sons Daughters Number Candidate number of daughters Nationality text Candidate Nationality Marital Status text Candidate marital status Position text Candidate position Page 58 of 77

60 Candidate Certificates Candidate Certificate ID text Unique certificate ID Issuing Authority text Issuing Authority of certificate Date Issued text Certificate date issued Expiry Date text Certificate expiry date Certificate Name text Certificate name Employment Record Agency Employment Record ID text Employment record unique ID Start Date text Employment record start date End Date text Employment record end date Ship Name text Name of the ship during employment Owner text Owner for the specific employment record Reason Of Sign Off text The reason of the sign off regarding employment Ship Type text The type of ship Engine Type text The type of engine Rank text The type of rank Position text The type of position Find Recruitment Requests Parameters The table below lists the required and optional parameters that this operation supports. Table A.4.5: Find Recruitment Requests Parameters Parameter Name Type Description Required parameters Candidate Crew text/xml Contains different information regarding curriculum Application vitae. See Section Response The table below describes the response that returns in a successful operation call Table A.4.6: Find Recruitment Requests Response Parameter Name Type Description Recruitment Requests text/xml A list containing all the matched RRs based on CCA. List Page 59 of 77

61 Errors The table below identifies error messages that the API could return in response to a call to this method. Return Value Page 60 of 77 Table A.4.7: Find Recruitment Requests Response Errors Error Error Type User Message Code 1 Internal Error Service Exception 2 Not Found No matched CCA found 3 Required field missing Missing parameter: Candidates details The table below describes each field of the return values for the specific operation Table A.4.8: Find Recruitment Requests Return Value Field Name Type Description Recruitment Request General Information Date Issued Date Time The date, assigned by the user, on which this request was issued Start Date Date The start date of request Time Evaluation Status Evaluation Status Value text Value of the request evaluation status Recruiting Agency Recruiting Agency Name text Name of recruiting agency Contact Person Username text Username of contact person Password text Password of contact person text of contact person Telephone text Telephone of contact person Name text Name of contact person Surname text Surname of contact person Recruiting Company Recruiting Company Name text The name of company seeking for employees Address text Address of recruiting company Telephone text Telephone of recruiting company text of recruiting company PO BOX text Post office box of recruiting company Vacancy Vacancy Title text Title of vacancy Vacancy NO Number Unique vacancy number

62 Field Name Type Description Min Years In Rank Number Minimum years of working experience in the Rank Age Range Start Number Employee age from Age Range End Number Employee age to Description text Description of vacancy Ship Type Ship Type Value text Type of ship Engine Type Engine Type Value text Type of engine Rank Type Rank Value text Type of rank Position Position Value text Type of position Nationality Nationality Value text Type of nationality Vacancy Certificate Vacancy Certificate ID text Vacancy certificate unique ID Certificate Name text Certificate name Weighted Profile Weighted Profile ID text Weighted profile unique ID Weighted Profile Name text Weighted profile name Weighted Certificate Weighted Certificate ID text Weighted certificate unique ID Max Weight Number Maximum value of assigned weight Score Number Score for the specific certificate Activated Yes / No Indicator if the certificate is activated or not Description text Description of the certificate Certificate Name text Name of the certificate Weight Weight Values Number Value of the assigned weights Weighted Attributes Weighted Attribute ID text Weighted attribute unique ID Weighted Attribute Value Number Value of the weighted Attribute Max Weight Maximum weight for the specific attribute Activated Indicator if the attribute is activated or not Attribute Name Name of the attribute Page 61 of 77

63 Maritime Financials Maritime Accounting and M.I.S. Parameters The table below lists the required and optional parameters that this operation supports. Response Table A.5.1: Maritime Accounting and M.I.S. Parameters Parameter Name Type Description Required parameters Maritime financial text Various Maritime financial information Information s The table below describes the response that returns in a successful operation call. Table A.5.2: Maritime Accounting and M.I.S. Response Response Name Type Description Financial Reports text Useful reports based on the financial information Errors The table below identifies error messages that the API could return in response to a call to this method. Table A.5.3: Maritime Accounting and M.I.S. Response Errors Error Code Error Type User Message 1 Internal Error Service Exception 2 Required field missing Missing parameter: Financial information Budgeting System Parameters The table below lists the required and optional parameters that this operation supports. Page 62 of 77 Table A.5.4: Budgeting System Parameters Parameter Name Type Description Required parameters Maritime budgeting text Various budgeting information regarding a Maritime Information s company

64 Response The table below describes the response that returns in a successful operation call. Errors Table A.5.5: Budgeting System Response Response Name Type Description Financial Reports text Useful reports based on the budgeting information (i.e. profit, costs) The table below identifies error messages that the API could return in response to a call to this method. Table A.5.6: Budgeting System Response Errors Error Error Type User Message Code 1 Internal Error Service Exception 2 Required field missing Missing parameter: Budgeting information Payment Module Parameters The table below lists the required and optional parameters that this operation supports. Response Table A.5.7: Payment Module Parameters Parameter Name Type Description Required parameters Maritime payment text Various payment information regarding a Maritime Information s company The table below describes the response that returns in a successful operation call. Table A.5.8: Payment Module Response Response Name Type Description Payment actions text Useful actions for supporting payment operations. (i.e. create invoices) Page 63 of 77

65 Errors The table below identifies error messages that the API could return in response to a call to this method. Table A.5.9: Payment Module Response Errors Error Error Type User Message Code 1 Internal Error Service Exception 2 Required field missing Missing parameter: Budgeting information Ship Operations Ship Status Parameters The table below lists the required and optional parameters that this operation supports. Response Table A.6.1: Ship Status Parameters Parameter Name Type Description Required parameters Vessel ID text Unique identifier for vessel (Ship Identifier) Vessel name text The name of vessel Navigational status text e.g. under way, anchored Latitude/Longitude text The current Latitude/Longitude Positional Accuracy ind. text Indicator of positional accuracy Direction text The direction of ship The table below describes the response that returns in a successful operation call. Table A.6.2: Ship Status Response Response Name Type Description Optimization text Optimization information regarding the current status of the Message ship Page 64 of 77

66 Errors The table below identifies error messages that the API could return in response to a call to this method. Table A.6.3: Ship Status Response Errors Error Error Type User Message Code 1 Internal Error Service Exception 2 Not Found No ship found 3 Required field missing Missing parameter: Ship Status Voyage Information Parameters The table below lists the required and optional parameters that this operation supports. Response Table A.6.4: Parameters Parameter Name Type Description Required parameters IMO Number text Unique identifier for vessel (Ship Identifier) Ship Name text The name of vessel Current Voyage ID text The current ID of Voyage Type of ship text The type code of ship ETA Date Estimate Time Arrival Time ETD Date Estimate Departure Time Time Destination Code text The code of destination Destination Name text The name of destination The table below describes the response that returns in a successful operation call. Table A.6.5: Ship Status Response Response Name Type Description Optimization text Optimization information regarding the voyage information Message Page 65 of 77

67 Errors The table below identifies error messages that the API could return in response to a call to this method. Table A.6.6: Ship Status Response Errors Error Error Type User Message Code 1 Internal Error Service Exception 2 Not Found No ship found 3 Required field missing Missing parameter: Ship information Cargo Details Parameters The table below lists the required and optional parameters that this operation supports. Parameter Name Type Description Required parameters Consignment ID Text The unique identifier for consignment From Vessel ID Text The unique identifier of vessel From Voyage ID Text The current ID of Voyage To Vessel ID Text The unique identifier of vessel To Voyage ID Text The current ID of Voyage Terminal/ Port Text The codes of terminal and port Container Number Text The unique identifier of container Container Type Text The type of container Table A.6.7: Cargo Details Parameters Response The table below describes the response that returns in a successful operation call. Table A.6.8: Cargo Details Response Response Name Type Description Optimization text Optimization information regarding the cargo of ship Message Page 66 of 77

68 Errors The table below identifies error messages that the API could return in response to a call to this method. Table A.6.9: Cargo Details Response Errors Error Error Type User Message Code 1 Internal Error Service Exception 2 Not Found No ship found 3 Required field missing Missing parameter: Cargo information Page 67 of 77

69 Appendix B emar Access Points Access Points enable emar Ecosystem users to communicate each other in a securely and reliably way using electronic messages. In the emar Ecosystem they are the main entry points and provide controlled access to software services. Access Points can be considered as a gateway or bridge between the emar Ecosystem members. The way access points operates represent the concept of in which the user simply creates a message from relevant data, enters the destination address and presses send. The fact that no central platform required and with the adoption of a public key infrastructure access points addresses also the two important issues arising from electronic information exchanged: Security and ownership of information. Access Points hold a major role to the establishment of a scalable, secure and efficiency connectivity infrastructure. The main advantage arising by the adoption of Access Points is that it can be utilized from a large number of participants in the European Maritime Community. The above capabilities together with the efficient discovery functions provide the means to stakeholders to enter and quickly become part of the Ecosystem without the need to rely on point to point connections in order to establish the supported comprehensive set of Maritime Logistics Services. Access Points can be considered as the transport infrastructure for Logistics Ecosystem by providing a standard set of information types which Common Framework supports as mentioned in the previous section. Apart from that, Access Points are independent from the traditional approach for organize all the exchanged data where the resources involved in the process left their digital footprints scattered across multiple isolated systems. By following an entity centric approach all the digital data in the Technology Ecosystem is directly managed by each single resource. The communication protocol and the implementation of Access Points has been highly influenced and is largely compatible with the European Standard implementation of PEPPOL project Access Points and also comply with the Business Documents Exchange standard (BUSDOX). BUSDOX is document agnostic, meaning participants can transfer ANY kind of electronic document between ANY network. The main difference between BUSDOX and other document exchange systems is that BUSDOX is designed to support what is known as a 4 corner model. The 4 corner refers to the fact that the trading participants (such as buyer and seller) may exchange their documents via two (or more) intermediary service providers. An important advantage of this approach is that it gives the possibility to participants to access the network using their own Access Points provider and have immediate connectivity with all other participants on the network. The BUSDOX specifications comprises of the following components [4]: 1. The SML (Service Metadata Locator) and SMP (Service Metadata Publishing) 2. Process identifiers 3. The START and LIME protocols Page 68 of 77

70 The emar Access Points make use of BUSDOX and the above common definitions. The basic components of these definitions are described below. B.2 The Service Metadata Locator and Service Metadata Publishing The Service Metadata Publishing (SMP) allows the discovering and retrieval of information about services of specific participant businesses via different services. This is prerequisite for client applications to retrieve the metadata about the services for a requested participant business before the client can use the particular services to send messages to the participant business. The client looks up the information for participants using the DNS based Service Metadata Locator service which is a regular DNS resolve. The Service Metadata Locator (SML) gives the ability to client applications to discover a particular participant identifier and hence the associated SMP endpoint since there is one to one relation between the participant identifier and the SMP. A client uses this service in order to find where information is held about services for a particular participant business. The diagram below [4] represents the lookup flow for a client application contacting both the SML and the SMP. Figure B.1: Endpoint lookup with SMP and SML B.3 Process Identifier Process Identifier represents a process that a specific document type can participate in. The main elements of the process identifier are the identifier and the scheme which indicates the format of the process identifier since can be different from domain to domain. Page 69 of 77

71 B.4 The Lightweight Message Exchange Profile The Lightweight Message Exchange Profile (LIME) is an optimal solution for small and medium Enterprises (SMEs) to access Business Document Exchange Network (BUSDOX) infrastructure from the economic and the performance point of view. This is because the establishment of a communication using the LIME does not require hosting online endpoints; hence no firewall crossing and no server infrastructure. Additionally there are no requirements for supporting advanced WS * standards such as WS Trust, WS Reliable Messaging. Additionally only minimal requirements are necessary to support WS Security (authentication headers only). B.4.1 Advantages of LIME The main advantage of the Lightweight Message Exchange Profile is that it allows different systems to participate in the BUSDOX infrastructure without needing to access service metadata or host an Access Point. Instead, they rely on an Internet Service Provider (ISP) to provide Lightweight Message Exchange Profile (LIME) services to them. A simple analogy is Internet Large companies may run their own Simple Mail Transport Protocol (SMTP) server and proprietary clients to create and read messages, but individuals or small companies rely on an ISP to provide an SMTP Relay and POP3 or IMAP server. A summary of benefits that LIME brings to the emar solution include: It provides access over a simple HTTPS protected channel. It utilizes existing standards where appropriate. It lowers the cost of entry for SME s and individuals. The diagram below [5] shows a simple example flow in which an LC needs to send a message to a company which uses an Access Point called AP2. For the establishment of such a communication, LC only needs to be configured to talk to a single local access point (AP). Initially the user creates a message using the LC client. The requirements are that the business message complies with the BUSDOX specifications and that the correct business identifiers are made available to the LC. The LC creates the message, sends it to AP1 which initiates the message flow and causes the AP to create a fixed Endpoint Reference (EPR) Resource. The specific approach guarantees that messages delivered to the AP. When the message is delivered to the access point, it looks up the recipient s AP and transfers the message. The LC also polls the AP for any incoming messages. This is done by Get ting a list of available messages from the AP, and then individually retrieving each available message (if any) using another Get. Page 70 of 77

72 B.4.2 Technical Overview of LIME The profile defines a set of technologies that are used together: HTTPS and Basic Authentication for security SOAP 1.1 for the base communications WS Transfer as a standard approach to accessing the message channels BUSDOX specific headers to define standard metadata BUSDOX specific XML Schema to define the message list XML format Together these different technologies are used together to define a simple protocol that can allow an intermittently connected computer system to fully participate in a BUSDOX infrastructure so long as they have a Lightweight Message Exchange Profile Access Point (LIME AP) available. Figure B.2: The Lightweight Message Exchange [5] Page 71 of 77

73 B.5 Secure Trusted Asynchronous Reliable Transport (START) BUSDOX infrastructure is created through the communication of Access Points in a peer to peer model across the internet. The requirements for the form of the specific infrastructure and for the communication to take place are that each AP should know the endpoint address of others AP. This can be achieved with the use of BUSDOX Service Metadata Publishing Infrastructure [3] which enables the exchange of digital certificates and endpoint URLs and therefore automates the inclusion of new or modified APs. Such an exchange is achieved by holding the actual metadata information for a given participant identifier and document type combination. Moreover AP may communicate via optional Transport Profiles, but they must always offer a START endpoint by which any other AP may communicate. B.5.1 Advantages of START The goal of START is to support the message exchange between two or more ends, in a reliable and secure way using web services [7]. The profile is designed to: Enable the different implementers to build and therefore to gain access to BUSDOX with no further requirements or adjustments to implement other transport profiles. Provide detail description of the transport level requirements in a single document. Provide an efficient and interoperable communications pattern that APs can use to communicate very easy. Define the message exchange formats and patterns clearly. Guarantee that AP uses a secure transport protocol and thus the messages are reliably delivered between APs. This also includes provision of prerequisites for logging and proof of delivery for messages at the transport level. Guarantee confidentiality of exchange messages using transport level encryption. Guarantee integrity and authenticity of received messages using digital signatures and validation of these signatures. Support transfer of messages that are opaque to the Access Point Provide different formats of headers within the message envelope so Access Points can forward/transfer messages without requiring access to the business message. Provide a standard message for the authentication events in BUSDOX infrastructure in the form of SAML 2.0 assertions / tokens. Recipients can assume that senders have been authenticated by their token Issuers and obtain further proof via cryptographically signed tokens. Page 72 of 77

74 B.5.2 Technical Overview of START The secure trusted Asynchronous reliable Transport (START) defines a secure, reliable profile using a set of well known standards: SOAP 1.1 WS Addressing 1.0 WS Security 1.1 WS Transfer as a standard approach to accessing the message channels WS Reliable Messaging 1.1 SAML 2.0 A typical flow of START is shown in figure below and might be: 1. User C1 creates a specific format message along with the others required metadata such as sender recipient Identifier, identifier type, Process and Document identifier. 2. The message is transferred to Access Point AP1, including the above information: 3. AP1 uses the BUSDOX Metadata Lookup in order to identify the endpoints and keys for the Access Point handling the recipients messages (AP2). 4. AP1 gets creates the necessary tokens to include in the message transfer, i.e. X509 certificates and SAML 2.0 token. 5. AP1 includes the required SOAP headers containing recipient, sender and document type information 6. AP1 signs the message using Digital Signatures. 7. AP1 uses WS Reliable Messaging and TLS to transfer the message to AP2 as part of a reliable exchange. 8. AP2 responds with a signed proof of delivery message to AP1 using a signature confirmation method. 9. Finally AP1 logs a signed proof of delivery of the message. Page 73 of 77

75 Figure B.3: The START Transport Protocol [3] B.6 emar Access Points: Component View As described above Access Points are compatible with the equivalent implementation of PEPPOL and comply also with the Business Documents Exchange standard (BusDox). Technically Access Points consist of the following tiers as are described in the figure 9: Page 74 of 77

76 B.6.1 Client Tier Figure B.4: Tiered Component Diagram of the Access Point The client tier represents the different end user applications that are technically able to establish a communication through the Access Points. Generally every system which is exchanging electronic messages using the LIME protocol is acceptable to be included in this tier. B.6.2 Application Service Tier The specific layer comprised of the following sub tiers: 1. Communication Layer: Uses standard connectivity models such as SOAP in order to expose Access Point business logic to the end users system. 2. Business layer: Support the implementation of the application s main business logic. The specific layer contains also the implementation and functionality of START and LIME protocols along with the Access Point library which represents the underlying message business object and the common utilities for providing extra supportive functionalities between LIME and START protocol. 3. Data Access Layer: Manage the communication of the Access Point with the database and Data Access Layer: Manage the communication of the software with the database and it provides mostly standard functions to abstract Access Point specific database server implementation details. Page 75 of 77

77 B.6.3 Database Tier The specific tier is providing the data storage sub system. The specific sub system is responsible for storing business data in the relevant tables (e.g. messages, documents, participants, statuses, errors) well as data required by the system s infrastructure. The storage sub system comprised of a relational database based on the MSSQL Server. B.7 emar Access Points: Business View The figure below describes the emar access points from the business point of view: B.7.1 SMP Service Provider Page 76 of 77 Figure B.5: Business view of Access Point The Service Metadata Provider (SMP) provides the appropriate RESTful connectivity model in order to resolve final recipient s Access Point and in most of the times there is only one central upon SMP (Service Metadata Provider).In other words, SMP is used for retrieving the relevant information regarding the message recipient s AP. B.7.2 Access Point Service Providers Provide the necessary infrastructure for hosting the Access Points and enables business users wishing to exchange messages to access this infrastructure through the public web services. The specific providers can support the operation of Access Points for variety of users through the implementation in different heterogeneous platforms such as.net on Windows, Java on Linux etc. B.7.3 Access Point Service Consumers Consist of the variety of business users/ participants wishing to communicate between them using the emar Access Points. Users have the ability to register themselves and make use of a third party Access Point to exchange electronic messages.

78 B.7.4 On premises Access Point In case the business users/organization wants to host the Access Points locally and not to rely on any third party Access Point Service Provider they have the ability to host the Access Points locally and use them for their own private purposes. B.8 emar Access Points: Message Channels The main operation supported by the Lime protocol as mentioned before is the provision of the appropriate services for sending messages from the sender participant to the Access Point and for receiving messages from it as well. These operations are done by utilizing two independent WS Transfer endpoints: the Outbound Message Channel (OutMC for messages from sender to AP) and Inbound Message Channel (InMC for messages from AP to recipient). Based on the LIME protocol the AP should support the WS Transfer GET/DELETE on the InMC and the CREATE/PUT operations on the OutMC. Specifically supported services by the LIME protocol are: 1. Receiving the messages for delivery 2. Polling for messages destined for the participant 3. Downloading of specific message 4. Deleting messages from the AP B.7.1 Receiving the messages for delivery The service consists of two main steps as described in figure 11: Figure B.6: Participant sending a message for delivery (Operations on OutMC) Page 77 of 77

79 1. The LIME client creates an empty resource in the OutMC, using the WS Transfer Create: <wst:create/> The LIME protocol response to the above request and sending Endpoint Reference (EPR) of the resource that will be used to transmit the message: <wxf:resourcecreated>endpoint reference</wxf:resourcecreated> The message from the create request contains also different headers as defined in the BUSDOX which are used by the OutMC when sending the message: ids:recipientidentifier ids:channelidentifier ids:senderidentifier ids:documentidentifier ids:processidentifier Additionally the ids:messageidentifier is included in order the different messages to be uniquely identified when the receiver polling the list of messages. 2. In the second step the WS transfer PUT is used to send the message to the ERP as declared in step 1. These steps used also to discard any additionally headers are created which are not defined in the BUSDOX namespace. B.7.2 Polling for messages destined for the participant The specific function is executed when the LIME client wishes to retrieve the list of messages which others users have sent him. It uses the WS Transfer Get in which the InMC channel responds with a paginated XML list of the available messages, which are ordered by the time they were created. Responsible for listing the messages is the ERP through the use of Channel Identifier. B.7.3 Downloading of specific message In order for the LIME client to retrieve a specific message from the channel the same procedure as above is followed except that this time the ERP uses the both, the channel Identifier and the Message Identifier. B.7.4 Deleting messages from the AP The function is applied when the LIME client needs to delete a particular message from list that contains the messages sent by other users. It uses the WS Transfer Delete operation along with Channel and Message Identifier. After the deletion of the message, the LIME Server notifies the Core that the specified message can be deleted. Page 78 of 78