Alex Goussiatiner

Oleg Zhikharev

Sea-freight Automation Framework (SAF)
Developer Guide

Version 0.3, May 9 , 2019


SAF is an open source initiative to create a standard for automation framework, which offers a broader cross industry spectrum shifting away from today’s current inefficient practices to automated machine control in maritime logistics. When adopted by the maritime industry it should not only drastically increase the level of automation and reduce IT cost but provide cross-platform interaction to all parties involved in cargo handling operations and logistics.  
Developer Guide is the resource for IT and logistics  specialists taking part in the development and implementation of the SAF standard.


The current supply chain information technology paradigm can be characterized as follows:

Human Control Supply Chain Processes,  Manual Task Execution and  Data

Majority of the current business processes, including ones that are repeated regularly and don't require complex decision making are controlled and performed by humans. While executing various logistical contracts, personnel routinely make the phone calls, use emails, enter data in various WEB forms, track cargo in various online platforms, document  execution of the contracts, etc.

Large Monolithic Systems

Most Information Systems that are used in the industry are large, hard-to-change monolithic systems, with limited ability for dynamic adaptation to new technologies and business conditions.

It applies to operating platforms for Exporters, Shippers, Customs (Single Window Systems), Shipping Line, Railways, Marine Terminals (Terminal Operating Systems - TOS), Trucking Companies, Port Authorities (Port  Management Information System), etc.

This also applies to commercial  Integration Platforms, which support integration amongst operating systems and individual web clients: Commercial Cloudbase Integration Platforms, Port Community Systems (PCS), e-Payment Gateway Platforms, etc.

These systems and platforms vendors have centralized monitoring and control policies wrapped around with exorbitant pricing and contractual lock-in periods. More than often the closed architecture of these systems and platforms means that any enhancements and extensions are always undertaken at the vendor mercy and their in-house resource limitations which makes the engagement models extremely unproductive, ineffective and inefficient.

Process Information "Silos"

Business processes are divided into fragments ("Silos"),  which do not  exchange data.  For instance,  export container process is divided into the following fragmented “silos”:

As a result, there is no clear data visibility for the entire supply chain  process and participants are often working in isolation and are obliged to re-enter data multiple times.

Incommensurable User Interfaces

During a typical work day, a user performing repetitive standard task uses online platforms where the task is performed in completely different manner. For instance, the user interface for "export cargo booking by shipping line" is different for each TOS. Users are forced to create individual  accounts in multiple IT platforms and login separately to each of them.

No  standard definition for business roles, engagements and transactions

As a result, interactions between participants vary significantly, roles are not clearly identified, and business transactions are executed and recorded in various ways.

No Standard Application Programming Interface (APIs)

IT Platforms and Commercial Integration Platforms with the same designation don't have the same integration capabilities; they expose non-standard APIs and use various formats of messages such as: EDI, XML, comma-separated values files, Excel, etc.

Use of Multiple Internet Communication Protocols

Further complexity is that multiple application level communication protocols are used in the industry: FTP, Email, WEB Services, etc.

Not all participants have persistent online services on the Internet

Most of the shipping lines and freight forwarders have websites providing various online user services 24/7, however, vast majority  of  the shippers, trucking companies and customs brokers don’t have a presence on the Internet. Therefore, telephone calls, email messages and meetings are the only channels to  communicate  with them and the communication is regularly delayed when partners are not available.

These factors, when combined, result in:



SAF decomposes logistics processes into the smallest parts - standard engagements:  Contract Of Carriage Engagement, Export Customs Declaration Engagement, Empty Container Release Engagement, Truck Appointment Engagement, etc.

An Engagement is a process with single well-defined objective: container is transported from port of loading to port of discharge, exporter obtains Customs Declaration, etc.

An engagement  consists of physical tasks: cargo handling, transportation, printing of the documents, sending faxes, etc.  as well SAF data exchanges between the parties.

Participants and Roles

Participant is the company,  government agency, individual person in the supply chain,  which performs one of the three roles: Requester, Provider or Third Party in one or multiple  engagements.

In most cases Engagement is associated with a formal agreement between Requester and Provider and terminates when Provider receives monetary compensation for the services.

Engagement may also involve Third Party participant that  gets notified of the progress.

SAF facilitates exchanges of the  data between participants of the engagements as well as monitoring and control of processes. 


Any particular participant can also have one or multiple designations:  Exporter, Shipper,  Shipping Line, Customs, Marine Terminal, Trucking Carrier, Trucking Broker, etc.

SAF Engagement Matrices

SAF defines set  of typical sea-freight engagements, related designations and roles for the participants using matrices. See matrices for the Container Management, Vessel Management and Road Transport Management [Engagements].

Virtual Offices

Each SAF participant should have a permanent presence on the Internet - its own Virtual Office (VO). Virtual Office is a computer system (or systems)  that facilitates the participant roles in the engagements. SAF network  is Peer to Peer network  which consists of Virtual Offices as the nodes.

Virtual Offices:

Chain Of Engagements

Virtual Offices  will be taking part in multiple engagements at the same time. As a result, temporary chains containing multiple VOs will be formed  to facilitate transfer of data from one engagement to another and breaks down information barriers (“silos”).

The following diagram represents example of the Chain Of Engagement for the Ocean Transport (Contract Of Carriage) processes. In the diagrams nodes are representing Virtual Offices for the participants and the edges are representing engagements. End-points of the edges are describing roles: “P” stands for “Provider” and “R” stands for “Requester”. White titles are representing designations for the participant : Shipper, Freight Forwarder. Shipping Line, Consignee.

SAF Standard API

SAF provides formal definition of the standard engagements using Proto 3 Data Definition Language (https://developers.google.com/protocol-buffers/docs/proto3). SAF engagements definitions are  published in the GitHub (https://github.com/saf-project/api).

The engagement definition describes sequence of the messages exchanged between participants during execution of the engagement and the content of the messages.

Proto 3 supports  automatic generation of the data access classes for SAF messages for variety of modern programming including Java, GO, C++,Node.js, Ruby.

Internet Protocols For Message Exchanges

SAF Binary Proto 3 messages can be exchanged between VOs using variety  of the Internet communication Protocols such as Email, FTP,  REST Web Service Protocol (with JSON or XML payload).

Enterprise Level VOs can also use gRPC protocol (https://grpc.io/ . In this case, SAF APIs are used as input to automatically generate idiomatic gRPC client and server stubs in a variety of programming languages.

SAF Registry

To  facilitate discovery of the Virtual Offices and  communication between them, participant shall obtain unique SAF registration number and enroll  VO in the SAF centralized online registry. The registry record should contain general information about the company: company name, designations, address , phone number, etc., as well as SAF specific information. Participant shall list all engagement roles the company will perform including communication option  (end point) for the role: protocol, email address, URL, etc.

Sender Authorization

Message Sender  authorization in SAF using  gRPC or RESR  protocols  will require use of OAuth2 protocol (see https://oauth.net/2/) . In this arrangement:

Implementation of the SAF can lead to the following positive shifts:

Current State


Human Control Supply Chain Processes, Manual Task Execution and  Data Re-Entry.

Machine Control Supply Chain with process flow automation spanning over all supply chain participants with less dependency on human availability and efficiency. No data re-entry.

Large Monolithic Platforms.

Well defined granular functional services (applications), integrated when required with existing platforms.

Process "Silos".

Full integration between processes.

Incommensurable User Interfaces for online services and multiple sign-on.

Unified user interfaces for all online services, single sign-on.

No standard definitions for participant roles, engagement processes, messages  and transactions.

Standard definitions for the participant roles, engagement processes, messages  and transactions written in Proto 3 data definition language.

No Standard Application Programming Interface (APIs).

Standard APIs written in Proto 3, which describe data exchanged by the Virtual Offices

Not all participants have persistent online services on the Internet.

Online presence of all supply chain participants.


   Sea-Freight Automation Foundation (http://www.saf-project.org/)