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.

After setting up the connection to the data source, you can customize data retrieval by defining 1-2 chains of endpoints for each widget data source. Chains allow for multi-step data-fetching processes, where each endpoint can supply data for specific widget fields. Here’s how it works:

Setting Up Chains and Requests

1. Adding Chains and Requests:

   • Use the Add Chain button in the Parameters tab to create a new chain. Each chain can include multiple requests (endpoints).

   • By default, the widget starts with one chain and one request.

   • Additional requests can be added within a chain using the + button in the Requests section.

2. Configuring Requests:

   • For each request, you can define the URL Template, Variable Names, and Object Path. These settings specify how data is retrieved from the data source.

   • The first request in a chain must use an Object Path to fetch data dynamically.

   • Subsequent requests can include either an Object Path or a JSON Path to pull data from the response of the previous request in the chain.

3. Dynamic Filters:

   • Dynamic filters can be applied using variable placeholders (e.g., {{variableName}}) in the URL path, request body, or headers. These variables are dynamically replaced with actual values when the widget loads.

   • Use the Variable Name and Object Path fields to define these dynamic parameters.

4. Managing Chains and Requests:

   • A chain can be deleted by clicking the trash icon next to it. Requests within a chain can also be removed individually.

   • At least one chain with one request must remain.

To populate your widgets with data from your source, you can map several fields to one request or select different requests from a chain. Each field is linked to a specific JSONPath expression that extracts the desired data. By combining requests and chains, you can effectively handle more complex data retrieval needs.

Mapping Fields to Chains and Requests

1. Select the Chain and Request:

   • In the Fields tab, use the Chain Sequence and Request drop-downs to specify which endpoint to use for a particular field.

   • Each field must be assigned to one endpoint within the chain structure. For example, you can choose Chain 1 - Request 1 for one field and Chain 1 - Request 2 for another.

2. Define the JSONPath:

   • Use a JSONPath expression to extract the desired data from the endpoint’s response.

   • To combine results, separate multiple JSONPaths with a semicolon (;). The combined values will be concatenated with a space.

3. Array Handling:

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

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.

Basic example

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"

List example

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"

Alternative list example

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"

Filtering

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"