How do I build a Mesa dashboard?

Important

This feature is in Early Access and is subject to change.

Mesa helps you visualise your LUSID data as a live dashboard of charts, grids, and other widgets. In this tutorial, we’ll build a dashboard from transactions data and add widgets to display that data in different ways.

Prerequisites

Before getting started, ensure you have:

• Familiarised yourself with source types, source factories, sources, workspaces, and widgets; see Understanding Mesa architecture.

• A portfolio with transactions in LUSID; read more on transactions.

• A workspace to save your dashboard in; read more on workspaces.

Step 1: Open the Mesa UI and choose a workspace

1. Navigate to the Mesa UI (https://<your-domain>.lusid.com/mesa/dashboards).

2. From the dropdown, select the workspace you want to save your dashboard in.
   

3. Click New dashboard in the top right.

   

Step 2: Add a source

A source is the live feed of data that your widgets display. There are two ways to create a source:

• Directly from a source type: Set parameters on a raw data set yourself.

• Using a preconfigured source factory: Created by someone in your organisation, source factories configure the source for you. Some parameters may be locked with preset values that you can’t change, while editable parameters allow you to specify your own values; see How do I configure a Mesa source factory?

In this tutorial, you create a source directly from the Transactions source type.

1. Click Manage sources in the top right.
   

2. Click Add source and choose Transactions. Note that source factories appear in the same list as raw source types.
   

3. Name the source so you’ll recognise it when you start building widgets.

4. Specify values for the source type’s parameters. For transactions, specify the following:

   • Portfolio scope: The portfolio scope to display transactions data for.

   • Portfolio code: The portfolio code to display transactions data for.

   • Effective range: Optionally, only display transactions with an effectiveAt within a particular time period. You can specify relative time periods, for example T-1, This week, or This quarter.

   

5. Optionally, select Show all parameters from the dropdown to add extra columns to your source, such as properties and address keys. For each additional parameter, specify the following:

   • Property key: The 3-stage property key or queryable key.

   • Name and Description: An optional friendly display name and description for the parameter; if you leave these blank, Mesa uses the property’s existing display name and description.
     

     Note

     You can click Edit parameters JSON to supply parameters as a JSON block instead of entering each parameter manually.
     

6. Click Create source and check the preview to confirm Mesa has fetched your data. Note that if you make changes to your parameters, you must click Apply to update the preview.
   

Once you’ve created the source, Mesa fetches your transactions data, waits for 60 seconds, then begins the next data refresh. If you instead choose a source factory with Preload enabled, Mesa fetches the data in advance, so it displays as soon as you open your dashboard.

You can use this source in as many widgets as you like, and each widget can show a different view of it. You can also add multiple sources to a dashboard.

Step 3: Add widgets to your dashboard

A widget is a single visualisation on your dashboard. Each widget reads from a source, then filters, groups, and sorts that data before displaying it.

In this tutorial, you add:

• A grid to see transactions row by row

• A pie chart to summarise transactions

To add a widget, click Add widget in the top right and select a widget type from the dropdown.

Adding a grid widget

1. Click Add widget and choose Grid from the dropdown.

2. Specify a friendly Title for the grid in the right-hand panel.
   

3. From the dropdown, choose the source you created in Step 2.
   

4. Optionally, click Add transform to:

   • Aggregate rows

   • Filter rows

   • Limit the number of rows

   • Add a Progress column showing where a value sits between a lower and upper bound

   • Sort the rows by a particular column

The following options are available for you to customise the look and actions in the widget:

• Use the Display settings to customise the header and footer style for your dashboard, and add a flair.
  

• Use the Interaction > Row menu fields to add action buttons to each row in the grid.
  

• Use the Grid fields to choose which columns to show or hide, and customise each column, for example to specify data formats and decimal places, or choose a column colour and width.
  

Adding a pie chart widget

To create a pie chart, click Add widget and choose Pie chart from the dropdown. As with creating the grid widget, specify a friendly Title, choose your source, and optionally add a transform operation and visual customisations.

For example, to show the total value of each transaction type, add an Aggregate transform that:

• Groups by the transaction Type

• Sums the Total consideration field

Step 4: Arrange and save your dashboard

1. Drag your widgets into the order you want, and resize them to suit your data. You can use the padlock icon in the top right to lock widgets in place.
   

2. Click Save to save your dashboard to your workspace.
   

When you save your dashboard in a workspace, other users with access to that workspace can view it.

Your saved dashboard should show your transactions data in a grid and pie chart:

The above image also shows a small Stat widget, which displays a single statistic, such as today’s total number of transactions.

Next steps: Let users change source parameter values

You can add an input so anyone viewing your dashboard can change a parameter value without editing the source. For example, you might add a date range input that allows users to change the period to view transactions for.

To do this:

1. Open your dashboard in edit mode and click Add input.
   

2. Select an input type from the dropdown, for example Date range.

3. Specify a unique Id, and a Name to display on the dashboard.

4. With your input created, go to Manage sources and click the Use an expression icon next to the parameter you want users to control, then enter the input Id.
   

5. Click Save.

Once you save the dashboard, the input appears at the top. When a user changes its value, Mesa fetches the new data straight away.