Knowledge Base
About DataloyRelease NotesAPI DocumentationJava VMS Documentation
Release 8.0
Release 8.0
  • Knowledge Base
  • Voyage Management System
    • VMS: Step-By-Step Guides
      • Vessels
        • Create Vessels
        • Copy Vessel
        • Find Vessels
        • Voyages & Port Calls
        • Main Vessel Description
        • Speed & Consumption
        • Load & Discharge Rates
          • Manage Load And Discharge Rates
        • Internal Data
        • AIS & Weather Reports
        • AIS-subscription
        • View Vessel Route from Previous Port to Next Port
      • Voyages
        • Create New Voyages
          • Create Voyage Charterer
          • Create Time Charter Out
          • Create Voyage From Template
          • Create Voyage Without Cargo
        • Find Voyages
        • Maintain Voyages
          • Overview
            • Vessel
            • Cargo
            • TC
            • Schedule
            • Profit/Loss Summary
              • Analysis
            • Speed & Consumption
          • Cargo
          • Bunkers
          • Various Cost/Revenue
          • Organisational Data
          • Invoices
          • Related
          • Voyage Functionalities
            • Converting Voyage to Template
            • Change Voyage Status
            • Swap Vessel
            • Configure Voyage as a “Last TC Voyage”
            • Change Voyage Reference Number/Voyage Number and Voyage Starting Year
            • Voyage Comparison
        • TC Voyages
        • Create Laytime Calculations
        • Delete Voyages
        • Voyage Map
        • Voyage Schedule
        • Voyage Edit Schedule
        • Voyage Alternative Routes
        • Voyage Functions
          • Sensitivity Analysis
          • Intake Calculation
        • Long Time Charter (TC) Voyage
        • Voyage Bunkers
      • Cargoes
        • Create New Cargoes
          • Create Cargo
          • Create Cargo From CoA Template
          • Create Cargo on TC Voyages
          • Create Cargo by Importing from Excel
          • Create Cargo From Existing Cargo
        • Find Cargoes
        • Maintain Cargoes
          • Cargo drawer
            • Main Details
            • Sub-cargoes
            • Various Cost/Revenue
            • Commissions
            • Freight Rate Tiers
            • Payment Terms
            • Comments
            • Cargo Drawer Actions
              • Allocate Cargo
              • Change Cargo Status
              • Delete Cargo
              • Relet Cargo
              • Convert Cargo to Relet/Non-Relet
              • Transship and Preship Cargo
              • Transfer Cargo
              • Connect Cargo to CoA
              • Remove CoA from Cargo
        • Template Cargoes
        • Capacity Plan
        • Sub-cargo
        • View Cargo History
      • Port Calls
        • Find Port Calls
        • Maintain Port Calls
          • Days Extra In Port
          • Speed Order
        • Register Noon Reports
        • Register Arrivals
        • Register Berths
        • Register Unberths
        • Register In Port Reports
        • Register Departures
        • Use Cost from Service Orders
          • Automating the Use Cost from Service order
        • Port Call Bunkers and Overview
        • View Service Orders on Port Calls
        • View Bunker Orders on Port Calls
        • View Vessel Reports on Port Calls
        • View Port Log on Port Calls
          • Stoppages
      • Port Costs
        • Find Port Costs
        • Maintain Port Costs
        • View Service Orders of Port Costs
      • Contracts of Affreightment
        • Create Contracts of Affreightment
        • Maintain Contracts of Affreightment
        • Find Contracts of Affreightment
        • Contract of Affreightment Lines
          • Find Contract of Affreightment Lines
          • Create Contract of Affreightment Lines
          • Maintain Contract of Affreightment Lines
          • Template Cargoes
            • Create Template Cargo
            • Maintain Template Cargo
            • Find Template Cargo
      • Time Charter Contracts
        • Create Time Charter Contracts
        • Maintain Time Charter Contracts
          • Duration and Rates
            • Create Duration and Rates
          • Notices
          • Comissions
          • Payment Terms
          • View Speed & Consumption
        • Print Statement of Account
      • Broker Commissions
        • Create Commissions
        • Find Broker Commission
        • Maintain Broker Commission
      • Bunker Orders
        • Create Bunker Orders
          • Create from a port call
          • Create bunker order from scratch
        • Maintain Bunker Orders
        • Stem Bunker Orders
        • Register Delivery Against a Bunker Order
        • Cancel Bunker Order
        • Delete Bunker Order
      • Service Orders
        • Create Service Order
        • Maintain Service Order
        • Delete Service Order
      • Laytime Calculations
        • Create Laytime Calculation
        • Find Laytime Calculation
        • Delete Laytime Calculation
        • Maintain Laytime Calculation
          • Status
          • Drawer Fields
          • Manage Cargo Ports
            • Cargo Port Fields
            • Statement Of Facts
              • Event
            • Timesheet
      • Bills of Lading
        • Create Bills of Lading
        • Attachments
        • Edit Bills of Lading
        • Delete Bills of Lading
        • Print Bills of Lading
        • Print Sea Waybills
      • Offhire
        • Create Offhire
        • Find Offhire
        • Maintain Offhire
          • Delete Offhire
          • Copy Offhire
          • Status
          • Overview
          • Various Cost/Revenue
          • Comments
      • Vessel Reports
        • Find Vessel Reports
        • Create Vessel Reports
      • Voyage Analysis Dashboard
        • Log In
        • Viewing and Managing Deviated Voyages
          • Viewing and Managing Deviated Voyages
          • Viewing Post Voyage Analysis Detail
          • No Freight Received
      • Invoices
        • Invoices List
        • Pending Invoices
        • Assembling Invoices
        • Invoice Drawer
        • Printing Invoices
        • Reversing an Invoice
      • Bunker Transactions
      • Accruals
        • Accruals
          • Batch Post Accruals
          • Generate Accruals
          • Find Accruals
          • Maintain Accruals
        • Bunker Stock Adjustments List
          • Batch Post Bunker Stock Adjustments
          • Bunker Stock Adjustment Drawer
        • Actuals list
        • Time Correction list
      • Status Transitions
      • Webhook Subscriptions
        • Create Webhook Subscription
        • Find Webhook Subscription
        • Maintain Webhook Subscription
          • Overview
          • Notification
      • Setup
        • Users
          • Create Users
            • Create a Vessel Master user
          • Maintain Users
            • Change User Passwords
          • Find Users
          • Disable Users
          • Multi-Factor Authentication (MFA)
            • Guardian Multi-Factor Authentication (MFA)
        • Security Roles
          • Find Security Roles
          • Create Security Role
          • Maintain Security Roles
        • Security Groups
          • Security Group Aliases
          • Find Security Groups
          • Create Security Group
          • Maintain Security Groups
        • System Settings
          • General
          • Invoicing Preferences
        • Data Control
        • Widgets
      • Master Data
        • Banks
        • Bunker Categories
        • Bunker Types
        • Business Partners
          • Manage Business Partners
        • Companies
          • Manage Companies
        • Events
        • Ice Class
        • Individuals
        • Port
        • Restricted Areas
        • Taxes
        • Various Costs and Revenues
        • Vessel Types
      • EU ETS Compliance
      • Attachments
      • Audit Log
      • Comments
      • Notifications
      • Sorting and Filtering Lists
      • Customising List Columns
      • Export to Excel Sheet
      • Widgets
    • Oracle Database Compatibility
  • Fleet Allocation & Scheduling
    • FAS: Step-By-Step Guides
      • Capacity Plan
      • Fleet Plans
        • Open Positions Board
        • Scheduler Board
        • Cargo Management Board
          • Cargo Actions
        • FAS Voyages List
        • FAS Cargoes List
        • Voyage Actions
      • Scenarios
        • Find Scenario
        • Create Scenario
        • Maintain Scenario
        • Copy Scenario
      • Budgets
        • Create Budget Scenario
        • Template Voyages
          • Create Template Voyages
          • Find Template Voyages
          • Maintain Template Voyages
        • Budgeted Voyages
          • Find Budgeted Voyages
          • Bulk Updating Budgeted Voyages
    • Create Voyages (JVMS)
      • Create Commitment
      • Create Commitment from CoA
      • Create Commitment from Voyage Estimate
  • Dataloy Distance Table (DDT)
    • About Dataloy Distances
    • Routing and routing options
    • Custom Point using Latitude and Longitude
    • High-Risk Area (HRA) / Piracy Routing
    • Distances API
    • Distances Change Log
  • Dataloy Systems AS
    • Privacy Policy
    • GDPR Statement
    • Release Notes
Powered by GitBook
On this page
  • Creating a Widget
  • Contexts
  • Fields
  • Creating a widget data source
  • Data source information
  • Data source URL
  • Authentication
  • Parameters
  • Field mapping

Was this helpful?

Export as PDF
  1. Voyage Management System
  2. VMS: Step-By-Step Guides
  3. Setup

Widgets

Widgets in the VMS are dynamic components that seamlessly integrate with the system drawers. They provide real-time or updated information without opening dedicated applications or navigating multiple screens. By leveraging external APIs or data from the VMS itself, widgets offer you quick access to relevant information at a glance.

One of the key features of widgets is their flexibility in terms of customisation and the possibility to perform complex data extractions. The appearance and behaviour of widgets are highly customisable, including adjusting parameters such as font size, colour, layout, and content display.

Creating a Widget

To create a widget, go to Setup -> Widgets, and at the top right, click Create -> Create Widget.

Contexts

In the "Contexts" step, choose a primary object type, like "Vessel". This object will be the source when querying data later. Contexts determine where widgets can be used. A widget can't be shown in a drawer without the context that links the widget's object type to the object in that location.

If a widget displays information about a vessel in the "voyage-drawer" context, the "object path" linking the voyage to the vessel would be vessel. This allows the widget to access vessel data in the voyage drawer.

Fields

Field names are displayed as column headers in a widget list, with values in rows. List field styles are fixed. In a widget card, field names act as labels followed by their values. Widget fields control how information is shown, either on a card or a list. You can customise the styles or use the defaults.

Field value data types

Ensuring that the "Value Data Type" matches the type of value in the data source is crucial for accurately displaying values.

Value Data Type
Display

date

Date-time formatted according to user locale

double

Decimal numbers

integer

Normal integers without decimals

link

URLs or email addresses become clickable links. Field name is used as label in card

string

Strings without formatting

Creating a widget data source

To create a widget data source, go to Setup -> Widgets, and at the top right, click Create -> Create Widget Data Source.

Data source information

A link to the "home page URL" address will be shown on the widget card. This is for reference only and doesn't affect data retrieval.

The "Widget" field connects the data source to a widget, and once selected cannot be changed unless the Widget is deleted.

Data source URL

The base URL and HTTP method form the starting point of the request's URL, with the parameterised URL template appended to it.

Authentication

Widget data sources support various authentication methods, including username/password and token-based systems like OAuth 2.0.

Parameters

After setting up the connection to the data source, you can customise data retrieval by adding parameters. These can be dynamically taken from the widget object or set as static values. Depending on your data source and request type, you can include these parameters in the URL path, request body, or HTTP headers. This flexibility allows for precise data fetching, fitting various scenarios and data source setups.

To create a dynamic filter value, enter a "Variable Name" and select an "Object Path". If the parameter type is set to "URL Parameter" or "Request Body", insert the variable placeholder into the template using the syntax {{variableName}}. When the widget loads, the placeholder will be replaced with the real value from the main object.

Field mapping

To populate your widgets with data from your source, use a JSONPath expression for each field that matches the desired data. Separate multiple JSONPaths with a semicolon (;) to combine results with a space.

To display multiple rows in a list widget, ensure the JSONPath result from your source is an array.

Examples

The JSONPath syntax supports powerful filtering and functions. For a more comprehensive understanding and examples of how JSONPath expressions are written, refer to the detailed examples in the official documentation.

In this example, we extract individual values for use in a card-type widget.

Data source JSON response

{
    "fruit": "Apple",
    "size": "Large",
    "color": "Red"
}
JSONPath
Result

$.fruit

"Apple"

$.color;$.fruit

"Red Apple"

In this example, the data source response is structured with multiple objects of the same keys, so to create the necessary values for list-type fields we only need to access all objects with the wildcard operator * before accessing the key.

Data source JSON response

[
    {
        "fruit": "Apple",
        "size": "Large",
        "color": "Red"
    },
    {
        "fruit": "Banana",
        "size": "Medium",
        "color": "Yellow"
    },
    {
        "fruit": "Grapes",
        "size": "Small",
        "color": "Purple"
    }
]
JSONPath
Result

$..fruit

"Apple", "Banana", "Grapes"

$..size

"Large", "Medium", "Small"

$..color

"Red", "Yellow", "Purple"

In this example data source response the names of the fruits are in the keys, not a property value, so to get all the names of the fruits, we can use the keys() function.

Data source JSON response

{
    "sizes": {
        "Apple": "Large",
        "Banana": "Medium",
        "Grapes": "Small"
    },
    "colors": {
        "Apple": "Red",
        "Banana": "Yellow",
        "Grapes": "Purple"
    }
}
JSONPath
Result

$.sizes.keys()

"Apple", "Banana", "Grapes"

$.sizes.*

"Large", "Medium", "Small"

$.colors.*

"Red", "Yellow", "Purple"

In this example, we want to use different criteria to find particular values from the data source response.

Data source JSON response

[
    {
        "fruit": "Apple",
        "size": "Large",
        "color": "Red",
        "price": 4
    },
    {
        "fruit": "Banana",
        "size": "Medium",
        "color": "Yellow",
        "price": 3
    },
    {
        "fruit": "Strawberry",
        "size": "Small",
        "color": "Red",
        "price": 8
    }
]
JSONPath
Result

$..*[?(@.size=='Medium')].fruit

"Banana"

$..*[?(@.size=='Small' && @.color=='Red')].fruit

"Strawberry"

PreviousData ControlNextMaster Data

Was this helpful?