I picked the Sample Vault because it is the one that gets shipped when you are installing M-Files in evaluation mode and it contains some sample data, as its name suggests… Please note that since it is a rather old vault, data inside was created somewhere between 2004 and 2012. Therefore, in this blog, I will go back in time (yes, I can!) and consider that “today” is actually the “01-Nov-2011” (2011-11-01). In a real vault, you would use the dateToken “@today” instead, but for this blog, to allow you to reproduce the steps below, I chose that specific date since it gives interesting data to visualize.

1. What I am going to build

The target dashboard has eight widgets:

• Four KPI tiles in a row at the top: Active Contracts, Expired Contracts, Contract Expiry < 180d, No expiry date.
• One donut: Contracts by agreement type.
• One gauge (date-mode): days until the earliest/next contract expiry.
• One area: contract expiry per year and per agreement type.
• One table: all expired contracts (for review or sales purpose).

This layout fills the right pane with a clean “summary at the top, distribution in the middle, action items at the bottom” reading order.

2. Creating a new dashboard

The dashboard management is done on the M-Files Admin UI. To access it, open M-Files Admin -> Configurations -> Other Applications -> dbi services Business Dashboard -> Dashboard tab. Then click on the Add New button. The editor opens, by default in Visual mode with an empty canvas and the Dashboard Settings panel on the right:

3. Dashboard Settings

Before adding widgets, let’s configure the dashboard-level fields in the right panel. The below assumes you never updated the default values. If you would like to update the defaults so all future dashboards have your own, you can do it in the Configuration tab.

• Name: Contracts Snapshot (01-Nov-2011).
• Description (optional): Quick view of contracts: active, expiring, distribution..
• Auto-refresh enabled: No (leave off for now, you can flip it on later if needed).
• User can toggle: Yes (users can enable the auto-refresh).
• Export to PDF enabled: Yes.
• Export to CSV enabled: Yes.
• Drill-through enabled: Yes (this is what makes the chart elements clickable and it displays details about the matching objects).
• Leave the rest as default. There are enough query results to fetch all details, each user sees only the objects their M-Files ACL allows, etc.

4. The first KPI tile: Active Contracts

Click on the + Add Widget button in the footer. A blank tile appears on the canvas and the right panel switches to the widget config.

First, we set the widget basic details:

• Widget Title: Active Contracts.
• Description (optional): leave empty.
• Widget Type: KPI Number.
• Col Span: 3.
• Row Span: 1.

Then, we need to configure the source of the data we want to see:

• Object Type(s): Document (dropdown shows the vault’s object types).
• Class (optional): Contract or Agreement (automatically populated after selecting an object type).
• Aggregation Type: summary (already set automatically since it’s the only one supported by kpiNumber).

Optionally, we can configure one or more filters. Here, since we want to see only active contracts (i.e. that have an effective-through date superior or equal to today), then we need to apply a certain filter. Click on the + Add Filter button and a row appears:

• Property: Effective through (date) (from the property dropdown, the “(date)” is the data-type that is shown but it’s not part of the property name).
• Operator: greater than or equal (>=).
• Value type: dateToken.
• Value: 2011-11-01 (instead of “@today” in a real vault).

Finally, we define the aggregation (i.e. what to do with the results obtained) as well as the display section, which are optional graphical/rendering details:

• Reducer: count (default).
• Drill-through Columns (comma-sep): Agreement type, Effective through (the additional columns to add to table lists or drill-through details tables).
• Display Unit: contracts.

To validate that the configuration is correct, you can click on the Test Widget button in the footer. The Test Results panel expands on the right side, and shows a green OK, which confirms the definition is correct. So far, so good.

5. The other three KPI tiles

The next three KPIs follow the same pattern as the first one, with different filters.

5.1. Expired Contracts

With the 1st widget selected, click on the Clone Widget button. A new tile appears next to the first one, with exactly the same content. Simply update these fields:

• Widget Title: Expired Contracts.
• Operator (Filter): less than (<).

Click on the + Add Threshold button and a row appears:

• Value (Threshold): 1 (any value equal or above 1 will match).
• Color (Threshold): red or #e74c3c (color used if above value is reached).

5.2. Expiring in next 180 days

Click on the Clone Widget button again:

• Widget Title: Contract Expiry < 180d.
• Operator (Filter): between (from,to)
• Value (Filter): 2011-11-01, 2011-11-01+180d (instead of “@today, @today+180d” in a real vault).
• Color (Threshold): orange or #f39c12 (update the existing threshold and keep the value as 1).

5.3. No expiry date

Click on the Clone Widget button again:

• Widget Title: No expiry date.
• Operator (Filter): is empty (incl. absent) (no value field for this operator).

Click on the + Add Threshold button and a second row appears (keep the other one with 1-orange):

• Value (Threshold): 0 (any value equal or above 0 but below 1 (c.f. other threshold) will match. i.e. only valid if equal to 0).
• Color (Threshold): green or #27ae60 (color used if above value is reached).

At this point the canvas shows four KPI tiles. They each have colSpan: 3, so they sit nicely in a row of four totalling 12 (full width of the dashboard). You can click on Test Queries button (at the top) to validate that all four kpiNumber widgets are correct.

6. The donut: contracts by agreement type

Click on the + Add Widget button in the footer to add a new widget:

• Widget Title: By Agreement Type.
• Widget Type: Donut Chart.
• Col Span: 6.
• Row Span: 2 (chart widgets need height, see Post 3).
• Object Type(s): Document.
• Class (optional): Contract or Agreement.
• Aggregation Type: Group by Property (all objects with the same value of a specific property will be grouped together).
• Group-by Property: Agreement type (lookup) (the property to be used for the grouping).
• Drill-through Columns (comma-sep): Agreement type, Effective through.

7. The date-mode gauge: countdown to next expiry

The gauge is where things get more interesting. Here, I would like a dial showing how many days are left until the earliest/next contract expiry. This can be useful for making sure you never reach “0” (i.e. the date of today) on some tasks, like contracts renewal, period reviews of some documents, etc. You can see this as something similar to a fuel gauge in a car. If it reaches the minimum, you might be in trouble… The reducer is min on the Effective through property, and since this property is a date, it triggers date-mode automatically.

Add the sixth widget. You know the drill, + Add Widget:

• Widget Title: Closest Expiry.
• Widget Type: Gauge.
• Col Span: 6.
• Row Span: 2.
• Object Type(s): Document.
• Class (optional): Contract or Agreement.

Let’s add a filter to keep only valid contracts again: click on the + Add Filter button and a row appears:

• Property: Effective through (date).
• Operator: greater than or equal (>=).
• Value type: dateToken.
• Value: 2011-11-01 (instead of “@today” in a real vault).

• Reducer: min.
• Reducer Property: Effective through (date).
• Drill-through Columns (comma-sep): Agreement type, Effective through.

Now let’s add a first threshold: click on the + Add Threshold button and a row appears:

• Value (Threshold): 0 (so “today” = the contract expiry is very soon).
• Color (Threshold): red or #e74c3c.

Click on the + Add Threshold button and a second row appears:

• Value (Threshold): 40 (so “next month” = the contract expiry is coming).
• Color (Threshold): orange or #f39c12.

Click on the + Add Threshold button and a third row appears:

• Value (Threshold): 80 (so at least “2 months left” = the contract expiry is still far).
• Color (Threshold): green or #27ae60.

• Display Min (day offset): 0 (so “today”).
• Display Max (day offset): 180 (so “today” + 180 days).
• Display Unit: next expiry.

7.1. Sample Vault date limitation

Note: This widget will not fully work on the Sample Vault as-is, since the data is from 2011 and all contracts are already in the past. In a real vault, you would use @today as the filter value and set min/max to 0 and 180. The gauge would then show the number of days until the earliest active contract expires.

On the Sample Vault, since 01-Nov-2011 is roughly 5350 days in the past, you would need to set min to “-5350” and max to “-5350+180” to see a meaningful result. The exact offset depends on when you read this, which is precisely why date tokens like @today exist – they adapt automatically.

If I set the min/max offset to the accurate number of days since 01-Nov-2011, the gauge looks like this for end-users (that’s what It will look like on a real vault with @today and 0-180 values):

8. The area chart: expiry per year and per agreement type

Add the seventh widget. It didn’t change since earlier, it’s still + Add Widget…

• Widget Title: Expiry per Year and Agreement Type.
• Widget Type: Area Chart.
• Col Span: 12.
• Row Span: 2.
• Object Type(s): Document.
• Class (optional): Contract or Agreement.
• Aggregation Type: Group by Date Bucket (all objects with the same date bucket for a specific property will be grouped together).
• Date Property: Effective through (date) (the property to be used for the grouping).
• Bucket Size: year (the objects within the same year will be in the same group).
• Series Property (optional): Agreement type (lookup) (a second grouping level).
• Drill-through Columns (comma-sep): Agreement type, Effective through.
• Smooth Lines: Yes.

Note: Instead of an Area Chart, you can use a Line Chart or Bar Chart, these three are usually interchangeable and can give the same amount of information visually.

9. The table: expired contracts to review

The last widget is a table showing the list of all expired contracts. This can be used for review or for some sales purpose, as previously mentioned. So let’s + Add Widget one last time:

• Widget Title: Expired Contracts to Review.
• Widget Type: Table.
• Col Span: 12.
• Row Span: 2 (you can set 3 as well, for bigger table/lists).
• Object Type(s): Document.
• Class (optional): Contract or Agreement.
• Aggregation Type: List (list of individual objects).

Click on the + Add Filter button and a row appears:

• Property: Effective through (date).
• Operator: less than (<).
• Value type: dateToken.
• Value: 2011-11-01 (instead of “@today” in a real vault).

• Display Properties (comma-sep): Agreement type, Effective through, Owner.

10. Sanity check & Saving

Before saving, you can click on the Test Queries button from the toolbar to validate all widgets at once. The right-panel should list eight widgets, all green and without any warnings or errors. If something is wrong – a property name typo, an incompatible reducer / widget combination – this is where it would surface, with a clean message describing what to fix.

If it’s all green, then click on the Save button in the toolbar. The editor should display a message at the bottom saying it validated everything and then closes (you need to be quick to see the message). The Admin UI Dashboard tab refreshes, and the Contracts Snapshot dashboard now appears in the list, with its number of widgets and its description.

Now, let’s see what it looks like from an end-user perspective after all that work! You can open the M-Files Web or Desktop (or do a refresh CTRL+F5 / CMD+R if it’s already loaded), open the right pane by clicking on the Dashboard tab, and pick Contracts Snapshot from the dropdown (it should be displayed automatically if it’s your first dashboard). Every chart element should be clickable (drill-through is enabled), and the PDF / CSV export buttons should also be present.

See the first screenshot at the beginning of this blog post to see the final result that you can expect if you followed along the steps so far. Still, since you made it this far, here is what it looks like as a PDF Export:

11. Closing thoughts

I initially created the Business Dashboard with the JSON editor only, but I always had in mind that I needed to add a Visual Designer at some point, because not everybody knows how (or wants) to write JSON. Also, writing JSON directly requires you to know what is required, optional, supported or not supported. Even if the Test Queries and Save buttons both execute multiple layers of validations, to ensure everything you enter is supported, it still sends you warning after warning, error after error if you do not really know what you are doing. Therefore, the Visual Designer is great for that purpose, because you just click-through the details and you are guided all the way.

The Visual / JSON toggle at the top of the editor lets you switch between authoring paths at any time, and your work is preserved in both directions. If you prefer hand-editing JSON or need to do bulk changes, the JSON mode is always available—but most administrators find the Visual Designer sufficient for their day-to-day work.

Want to know more about this Business Dashboard? Contact us and we will be happy to showcase it on M-Files.

Quick access to previous blog posts of the series:

• Post 1 – Introduction to the Business Dashboard.
• Post 2 – The end-user experience: opening the panel, switching dashboards, drill-through, exports, favorites, sharing.
• Post 3 – The anatomy of a dashboard definition: the JSON structure that drives everything.
• Posts 4a, 4b, 4c – The widget catalog, split by type family: scalar widgets (kpiNumber, gauge), trend widgets (line, area), and distribution / tabular widgets (donut, bar, table).
• Post 5 – Writing queries: objectType, class, filters, date tokens.
• Post 6 – Aggregations and reducers.
• Post 7 – The Admin tab: actions, Visual Designer / JSON editor, validation, import / export, access control.

L’article M-Files BD – Putting it together with the Visual Designer est apparu en premier sur dbi Blog.

This is also where the Visual Designer lives. Some administrators write JSON directly, others stay in the visual canvas, others switch back and forth. All three workflows are supported, and the two modes are kept in sync at every moment.

1. Where to find the Admin tab

Once it has been installed (e.g. via Vault -> Right click -> Applications -> Install…), the Business Dashboard will be present in the M-Files Admin configuration page:

1. Open M-Files Admin (the desktop management application).
2. Connect to your server and open the target vault.
3. In the left tree, navigate to Configurations -> Other Applications.
4. Find dbi services Business Dashboard and click it.
5. You should end up on the Dashboard tab.

The first thing you will probably want to do is to look at the Configuration tab, that sits right next to the Dashboard one. This is where you can configure the Business Dashboard as needed.

1.1. The Configuration tab – “General” settings

At the time of writing this blog, the General section of the configuration is rather short. It only contains 4 settings:

• Table page size: controls the pagination of all tables (list & drill-through modals), i.e. the maximum number of rows that can be displayed before a new page is required. (default: 15).
• Default widget color: controls the base color of the widgets (end-user side), like the number inside the kpiNumber, the gauge and its pointer, the table header, the line and area. It’s only the base color, so it still gets updated/overwritten by the display.thresholds parameter of each widget. (default: #006eef – the M-Files “standard” blue).
• Default chrome color: controls the base color for the “chrome” things (end-user side), for example the links shown inside the tables, to navigate to objects, as well as the spinner when dashboards/widgets are loading. (default: #006eef).
• Admin UI accent color: controls the base color for the buttons (admin side), like Save, Test Queries, etc. (default: #006eef).

Exactly like any other M-Files configuration items, as soon as you modify one of these values, the “Save” and “Discard” buttons appear so you can either persist and remove what you just changed.

1.2. The Configuration tab – “New Dashboard Defaults” settings

The second section inside the configuration tab allows to overwrite the default settings for new dashboards. As I mentioned in previous blogs, a dashboard has around 10 configurable parameters, that controls things like which features are allowed, whether users can refresh or if it should be automatic, etc. All these parameters have a default value, which is usually “No” (disabled / do not bypass important checks).

This section will make it so that all dashboards created in the future will use your own personalized default values, so you don’t have to configure the same things over and over again. It doesn’t have any impact on already configured dashboards AND it doesn’t force anything. It is simply a replacement of default values, which means that you can still overwrite these settings inside each dashboards as required (because specific dashboards might have different needs).

• Auto-refresh enabled: controls whether the automatic refresh is enabled. (default: No).
• Auto-refresh interval (seconds): controls the interval between two automatic refresh. (default: 300).
• User can toggle auto-refresh: controls whether users can enable the automatic refresh. (default: No).
• Export to PDF enabled: controls whether the PDF export is enabled. (default: No).
• Export to CSV enabled: controls whether the CSV export is enabled. (default: No).
• Drill-through enabled: controls whether the drill-through is enabled, which also controls the navigation to target objects. (default: No).
• Drill-through max results: controls how many results will be paginated on drill-through modals. (default: 300).
• Server scan max results: controls how many results we can return when looking for objects. (default: 500).
• Skip template check: controls whether the “template check” are skipped. More on that later in this post. (default: No).
• Skip object permission check: controls whether the user’s ACLs are respected. More on that later in this post. (default: No).

1.3. The Configuration tab – “Logging” settings

The third section contains all the standard M-Files logging configurations. In there, you can enable the global logging, then create some specific targets, like a file target (writing to a log file on the local file system), event log target (writing to the Windows Event Log), database target (writing to a specific DB), etc…

These are usual M-Files configurations, so I won’t describe them all, but in short, you only have to enable the global logging, defining a target with the appropriate log level and target-specific details as you see fit.

2. The dashboard list and action buttons

The Dashboard tab shows all currently configured dashboards (or nothing if you have none yet) in an alternating-row list. Each row contains additional details such as the count of widget inside this dashboard, the access details (whether it can be accessed by everybody or if it’s restricted to some people/groups only) and the description.

Each dashboard row also has a compact icon button bar for quick access: ↑ ↓ 🖉 ⧉ ⎙ 🗑 (move up / move down / edit / clone / export / delete) (It took me so long to find these icons!). These per-row buttons provide faster access to the most common operations without opening a selector modal from the top-bar buttons.

Speaking of top-bar buttons, you saw them already, but at the very top, you can see global action buttons available from any of the tabs:

More on these actions lower in this blog post.

3. The editor: two modes, one source of truth

When you click Add New or Edit…, the editor modal opens. At the top of the toolbar, two buttons toggle between the modes:

• [Visual] (default): the “Visual Designer”, a form-based designer with a canvas of widget tiles and a side configuration panel.
• [JSON]: the “JSON Editor”, a manual code box that allows you to write JSON.

The two modes are kept in sync at all times. Switching from Visual to JSON shows the current visual state serialized, switching back re-parses the JSON so that the Visual Designer is also up-to-date.

The editor is split into four regions:

• The top bar shows main buttons to switch between modes, load an example dashboard (to give you some ideas), format JSON (when in JSON Editor mode), test all widgets at once or save.
• The left panel shows either the widgets display in Visual Designer mode or the JSON code block in JSON Editor mode.
• The footer bar (anchored below the canvas) has four buttons, to show the dashboard settings, add a new widget, clone an existing widget or test a widget. There is also a small place below these buttons kept for status messages, to let you know when something was done or if there are errors, etc.
• The config panel (right panel) shows the editable fields. In Visual Designer mode, it shows dashboards and widget configurations. In JSON Editor mode, it shows the user and group pickers only. Both modes also includes the “Test Results” which contains execution/validation details.

3.1. Visual mode

As said, the left panel contains the widget display, with their title, type, aggregation, objectType. It also display quick action buttons such as up-down or delete, so you can quickly re-arrange the widgets and get the visual look&feel that you want. The right panel contains the dashboard settings by default (which we described above already). When a widget is selected, the right panel will then display these different building blocks:

With this Visual Designer, you are guided by selecting things one by one. You don’t see ALL options right from the beginning, depending on what you select, only what is possible will be offered, so you can focus on what makes sense for you.

3.2. JSON mode

The JSON Editor is simply a code box which allows you to enter JSON. It shares the top-bar buttons with the Visual Designer, the only difference being the “Format JSON” one that is enabled only when in JSON mode.

I might extend this feature later, but for now there is no completion feature, it simply has a bit of highlighting so you can spot errors easily and allows for code drag-and-drop.

4. Validation

4.1. The two-stage validators

Whether you click on Test Queries (all widgets), Test Widget (1 widget) or Save and whether you are doing it from Visual or JSON mode, the engine will run a 2-stage validation of what you currently configured.

4.1.1. Stage 1

The first stage is simply a structural one. For example, are all mandatory fields present, are known values (e.g. widget types) within the accepted ones, etc. This is very fast and it doesn’t require a connection to the vault, so that we can already surface global issues.

Note: Only the “Import” feature bypasses the stage-2 validation and only performs a structural check. When using the import feature, we kinda expect that the JSON was exported from another vault and therefore if it existed inside a previous environment, it means that it is a valid dashboard. Doing the stage-2 validation on each import would considerably slow it down (especially if you import 10, 50 or even 100 dashboards at once).

4.1.2. Stage 2

The second stage is much more complex and it will verify if you made any mistakes by really checking what’s available inside the vault. This will mark typos such as wrong object types, classes or properties. It will also try to resolve value lists items that you references, to make sure they are indeed present. This is obviously slightly slower, but still completes within a couple seconds for most dashboards. It also gives you a good idea of how fast this dashboard will load for end-users, since it’s actually executing all queries.

Note: For Test Widget, the engine will only test one specific widget, as said earlier. Therefore, it automatically adds a valid dashboard structure around it so it can pass the stage-1 validation for the dashboard level. Only stage-1 validation of the widget level is tested and the query execution for the phase-2, obviously.

4.2. Errors and warnings

The Test Results panel shows three possible statuses per widget:

• OK: the query succeeded and the result is renderable.
• Warning (amber): the query succeeded but the result will probably not be rendered the way you would like to. A common occurrence is a date-valued reducer on a chart widget, where the message will tell you to switch to kpiNumber, table, or gauge.
• Error (red): the query failed. The message tells you which property name or class name to check or change.

Note: A warning will still allow the Save to complete, because even if it might not render, a placeholder widget will replace the expected chart. On the other hand, an error will prevent the Save operation because we shouldn’t persist something that is structurally or fundamentally wrong. Here is an example from the Example Dashboard where I specifically introduced some mistakes:

5. Import and Export

Dashboards live in the vault’s Named Value Storage (NVS). To facilitate transfer from DEV to QA/INT to PROD or any other environments you might have, an import/export feature was added on the M-Files Admin. To use it, simply click on the Import or Export… buttons.

First, the Export… one, open a prompt so you can select which dashboard you would like to export. On that prompt, there is also a button to Export All. If you select a single dashboard to be exported, the JSON file generated will have, by default, the name of the dashboard (you can set the name that you want, of course). If you chose to export all, then the name will simply be “dashboards-export.json” and inside, you will find an array of dashboard definition.

Once it has been exported, you can then Import it somewhere else (or on the same vault, it will merge it with existing dashboards – that’s why IDs are important!). Another prompt opens and you can then select a file (through Windows Explorer) or you can also drag-and-drop JSON to it. Its content is then displayed inside the prompt so you can take a look. Once you hit the import button at the bottom, it will quickly validate the dashboard definition and if everything is good, it will be imported into the vault.

6. The Reorder and Clone modals

Two smaller actions but these are still worth mentioning because they fix small but real pain points. The Reorder… one allows you to use the up-down arrows – same as from the dashboard list shown in the default Dashboard tab. But you have access to another facilitator with the global button: dashboards are numbered with a small text box that you can update. For example, if you have 5 dashboards, the last one will have a small text box with a “5” inside. If you update that value to “1”, then this dashboard will automatically become the 1st one. This allows for faster re-ordering than clicking 4 times on the arrow-up icon, especially when you have 50+ dashboards to manage.

If you have a good idea of what you want to build and you know that one of your dashboards is already pretty similar, then instead of recreating everything from scratch, you can use the Clone… feature. It allows the duplication of an existing dashboard into a new one. The new one will use new IDs for both the dashboard and all the widgets, and to be able to differentiate them, the name will have a ” (copy)” suffix. I see you coming – if you duplicate the same dashboard multiple times, it will be ” (copy 2)”, then ” (copy 3)”, etc.

7. Access control – two-level model

Access control in the Business Dashboard works on two distinct levels:

The two are independent. assignedTo says “you are allowed to open this dashboard”. skipObjectPermissionCheck says “once you are inside, do widgets show you everything or only what your own permissions allows you to see and read”.

7.1. assignedTo – who can open the dashboard

By default (no assignedTo field or an empty array), a dashboard is visible to everyone who has access to the vault. To restrict the access, you can define either a list of users or groups:

"assignedTo": {
  "users": ["Morgan.Patou"],
  "groups": ["Finance Team", "Management"]
}

Access is granted to any user who matches any entry (OR semantics), i.e. part of the users list or part of any of the group from the groups list.

7.2. skipObjectPermissionCheck – what data shows up

By default (“No”), M-Files permissions will be respected, so you cannot see things that you aren’t entitled to see. However, there are valid use cases where you would need to specifically bypass object-level permissions.

For example, you probably don’t want all your employees to see all the HR documents, all the contracts, etc. However, there are often KPIs that could be rendered “Public”, or at least given to a broader audience than the people that originally have access to these objects. Maybe you would like to share some executive or management reporting KPIs, some Sales Performance details, or some Security Information.

That is entirely up to you and, in addition, you control whether end-users can use the drill-through or not and what metadata the drill-through should show (if anything at all). Again, it’s not because you show KPIs that users will be able to find and read classified documents. M-Files permissions on the objects themselves (preview its content, listing all metadata, downloading the file, etc.) will always be respected. What the Business Dashboard allows is fully configurable, so there are no real security concerns.

When to use each:

• “No” (default): when different users should see different numbers based on their own M-Files ACL.
• “Yes”: when every authorized viewer should see identical numbers and performance matters (typical for overview dashboards that don’t go into details). Combine with assignedTo to restrict who can open it.

8. Performance

I already mentioned them in earlier posts, but I think it still makes sense to summarize it all again here, since we are talking about the Admin side of the Business Dashboard. There are multiple parameters that have performance impacts. Some of them are very low, some aren’t.

8.1 Performance gains

These are the things that will have either no negative performance impact or even show performance gains:

• exportToPdfEnabled / exportToCsvEnabled: these two parameters are similar in the sense that they only enable one specific feature and it has no performance impact, since it runs fully on client side. All the data is already available in the client’s dashboard, so it has no impact on the server.
• skipObjectPermissionCheck: by default, it will execute ACLs checks to ensure users only see objects they are entitled to. The way I implemented that means that whether you are doing server-level queries or user-level queries has absolutely no impact on the performance. In fact, it might be even faster to execute the ACLs checks, since you might return less objects that what the server would have access to. Therefore, the performance impact is null or slightly positive.
• objectType / class / count reducer / native filters: adding a restriction on class and adding native filters will mean less results to be fetched and processed. As previously said (c.f. Post 5), for optimal performance, make sure to restrict the objectTypes / class and apply native filters as much as possible. Therefore, adding these will definitively bring performance gains.

8.2. Potential for Medium / High performance impact

Depending on how you use them, these settings can have very low or very high impact on the performance of the Business Dashboard:

• autoRefreshEnabled / autoRefreshIntervalSeconds / userCanToggleAutoRefresh: control the refresh of widgets/dashboards. The impact depends on multiple factors, like how many users, widgets, objects fetched, etc… These will increase the “regular” load on the server, not really impact the loading speed… The performance impact can go from very low (e.g. refresh every 5 minutes with low-demanding widgets) to pretty high (e.g. refresh every 15 seconds with 10’000+ objects widgets)…
• serverScanMaxResults / drillThroughEnabled / drillThroughMaxResults: define the maximum results for the widget or the drill-through. When hit, a Partial results badge appears, to show results may be incomplete. These are basically fail-safe/lifeline, to make sure widgets do not try to retrieve the whole vault’s content. The performance impact will be important if you disable this (“0” = unlimited results) and if you try to fetch 100’000 objects.
• skipTemplateCheck / non-count reducers / post-filters: all these parameters means that there is a need to fetch additional metadata from the vault, for all objects. If you want to execute the template check, apply a non-count reducer on a property or a post-filter, you will first fetch all objects, and then, for each of them, fetch their associated metadata. As far as I culd see, M-Files doesn’t allow to return both objects and their metadata at the same time. The performance impact will be grow with the number of objects you fetch and need to process.

Note: The performance isn’t bad. There are a few tricks I implemented to make sure the performance stays pretty good, so you can load a dashboard fetching 5’000+ objects in less than 1.5 seconds, with the right configuration.

11. Wrap-up

The Admin tab is the place administrators will spend the majority of their time. The Visual Designer is there to lower the complexity of creating and managing dashboards. Even a JSON-averse administrator can build a full dashboard without ever opening the JSON editor. However, it is still available for power users that feel comfortable with it, as it gives them the flexibility, quick copy/paste, and bulk-edit comfort they can expect.

The next, and probably last, Post 8 will walk you through building a complete Contracts dashboard on the M-Files Sample Vault. I will use the Visual Designer only, so you can follow along and adapt it to your own vault.

Want to know more about this Business Dashboard? Contact us and we will be happy to showcase it on M-Files.

L’article M-Files BD – The Admin part est apparu en premier sur dbi Blog.

The aggregation is what transforms the set of matching objects into a value the widget can render. There are five aggregation types, six reducers, and one optional second dimension (seriesProperty). Together, they cover every widget shape from a single KPI number to a cross-tab pivot table.

1. The two-dimensional model

The aggregation has two complementary components:

• The aggregation type is the shape of the result: one value (summary), one value per group (groupByProperty), one value per time bucket (groupByDateBucket), one value per admin-defined range (groupByRange), or a simple list of objects (list).
• The aggregation reducer is the operation applied within each group (or over the whole matching set for summary): count (default), sum, avg, min, max, median. Note: The reducer is ignored for list.

In other words, type decides whether you get a number, a chart, or a table; reducer decides what that number, bar, or cell actually measures.

2. The five aggregation types

2.1. summary – one value over everything

summary reduces the entire matching set into a single value. By default it counts the matching objects. However, with a different reducer, you can make it compute a property aggregate in different ways. Here are a few example of summary aggregations:

// Total count of matching objects
"aggregation": { "type": "summary" }

// Total revenue of matching objects
// (sum all values from the "Amount" property)
"aggregation": {
  "type": "summary",
  "reducer": "sum",
  "reducerProperty": "Amount"
}

// Latest contract expiry date
// (display only the date with the highest value - drill-through still list all objects)
"aggregation": {
  "type": "summary",
  "reducer": "max",
  "reducerProperty": "Effective through"
}

The widgets that accept summary are kpiNumber, gauge, and table. If you followed this series, you probably saw a bunch of the first two, already. The last one, in this case, will render the value as a one-row table. For all other chart widgets (donut, bar, line, area), summary does not really make visual sense, as a single value cannot be plotted on an X-Y axis.

2.2. groupByProperty – one value per group

groupByProperty groups objects by the distinct values of a property (the propertyName) and applies the reducer to each group independently. Here are two examples:

// Count of matching objects per Agreement type
"aggregation": {
  "type": "groupByProperty",
  "propertyName": "Agreement type",
  "includeEmptyResults": "No"
}

// Total revenue of matching objects per Customer
// (sum all values from the "Amount" property for each Customer independently)
"aggregation": {
  "type": "groupByProperty",
  "propertyName": "Customer",
  "reducer": "sum",
  "reducerProperty": "Amount"
}

The supported fields are the following ones:

The widgets that accept groupByProperty are donut, bar, line, area and table. Basically, all charts widgets, plus the table which is kind of a Swiss knife, that works with everything.

2.3. groupByDateBucket – one value per time period

It is very similar to the groupByProperty, but the target must be a date / timestamp. Basically, something that contains a date, whether its only the date or a full date-time is fine. Because dates would probably be a bit too wide, there is a concept of buckets, to group dates by a pre-defined range that might make sense. The default time periods are day, week, month, quarter or year. Here are two examples:

// Count of contracts expiring per month
"aggregation": {
  "type": "groupByDateBucket",
  "propertyName": "Effective through",
  "bucketSize": "month",
  "includeEmptyResults": "Yes"
}

// Sum of invoice amounts per quarter
"aggregation": {
  "type": "groupByDateBucket",
  "propertyName": "Invoice date",
  "bucketSize": "quarter",
  "reducer": "sum",
  "reducerProperty": "Amount"
}

The supported fields are pretty similar to the groupByProperty:

Note: you would usually combine groupByDateBucket with a date filter to limit the range of results. Without filters, the chart would show everything from the earliest object in the vault to the most recent, possibly spanning decades. If that’s what you want to see, then that’s absolutely fine. However, most of the time, a filter like between @startOfYear and @endOfYear for an annual trend chart might be more appropriate.

2.4. groupByRange – one value per admin-defined range

This one is also very similar to the last two groupings. With the main difference that this is the only one that allows you to define the exact range.

2.4.1 The groupByRange itself

If you have a certain property that has a high cardinality, it might be difficult to display it with a groupByProperty. Let’s take for example the “Amount” property from before. When you want to apply math on it (sum/avg/min/max/median), then that’s fine because it only returns one value. But if you want to see the revenue themselves, without a prior grouping on something else (e.g. above we first group by “Customer”), then you would end-up with dozens/hundreds/thousands of groups? That’s where groupByRange shines, because you define the grouping (e.g. 0-1’000, 1’000-5’000, >=5’000).

You can use that grouping method with numeric / time / text / lookup properties. On the other hand, date / timestamp and boolean aren’t supported. The reason for that is simple: there is already groupByDateBucket for date / timestamp, and boolean can only have 2 values (Yes / No), so groupByProperty works just fine.

// Invoices by specific range
// 3 ranges: 0-1000, 1000-5000, 5000-10000
"aggregation": {
  "type": "groupByRange",
  "propertyName": "Amount",
  "boundaries": ["0", "1000", "5000", "10000"]
}

// Invoices by specific range, with open ranges
// 4 ranges: 0-1000, 1000-5000, 5000-10000, >=10000
"aggregation": {
  "type": "groupByRange",
  "propertyName": "Amount",
  "boundaries": ["*", "1000", "5000", "10000", "*"]
}

// Efficiency / speed of processing / duration of some actions / etc...
// 4 ranges: 0-30s, 30s-1min, 1min-2min, >=2min
"aggregation": {
  "type": "groupByRange",
  "propertyName": "Duration",
  "boundaries": ["*", "00:00:30", "00:01:00", "00:02:00", "*"]
}

// Customers by country name
// 3 ranges: A-F, F-M, >=M
// e.g. "France" in 2nd group, Switzerland in 3rd group
"aggregation": {
  "type": "groupByRange",
  "propertyName": "Country",
  "boundaries": ["A", "F", "M", "*"],
  "reducer": "count"
}

Again, the supported fields are fairly similar to the groupByProperty:

2.4.2. How boundaries work

Each boundary value marks the inclusive lower bound of a range and the exclusive upper bound of the range below it, except for the last range, which is fully inclusive. For example, ["0", "1000", "5000", "10000"] creates three buckets: [0, 1000), [1000, 5000) and [5000, 10000]. This means that a value of “1000” will end-up on the 2nd bucket only. A value of “5000” or “10000” will end-up on the 3rd bucket.

In addition, as you can see in the examples above, you can use a wildcard ("*") on either end: a leading "*" creates a bucket for everything below the first boundary, and a trailing "*" creates a bucket for everything at or above the last boundary.

2.5. list – one row per object

list are pretty similar to search results from M-Files, in the sense that it will just list something, with pre-defined columns. When using this aggregation type, the reducers have no effect, because it only lists objects but do not apply any modifications / computing on them.

// List all contracts with 3 specific columns
"aggregation": {
  "type": "list",
  "displayProperties": ["Agreement type", "Effective through", "Responsible person"]
}

For simple lists, the objects will be pre-sorted alphabetically but the user is then able to re-sort them, by each of the columns displayed. When drillThroughEnabled is set to “Yes”, then table rows become clickable and allows navigation to the object in question. There is no modal/drill-through in this case, since the table list already display the target object (no grouping).

3. The six reducers

As mentioned, all five aggregation types, except list, accept a reducer. You probably understand them already, but just as a quick table:

3.1. The date/time-valued reducer rule

When min or max is applied to a date, timestamp, or time property, the reducer returns the value and it will be formatted for end-users based on their localization / regional settings: e.g. DD/MM/YYYY for dates, DD/MM/YYYY HH:mm for timestamps (minute precision), and HH:mm:ss for times.

When sum, avg or median is applied to a time property, it allows you to compute a total (or average/median) duration for a certain activity. This might be useful if you have time-constraints.

Three widgets can render date/time values: kpiNumber (a single big number), gauge (switch to date mode, covered in Post 4a) and table (simple display in rows).

4. seriesProperty – the second dimension

The series details were already covered a bit in the posts 4b and 4c. But, this is the feature that turns a single-series widget into a multi-actor comparison. When you set a seriesProperty on a groupBy aggregation, the engine will automatically produce one series per distinct value of the series property. This allows a two-dimensional comparison.

The behavior per widget type is the following:

• line / area – one colored line per series, with an auto-generated legend.
• bar – one colored sub-bar per series (display.barLayout controls stacked vs grouped).
• donut – a multi-mini-pie grid, one donut per series, with a shared legend.
• table – a cross-tab pivot, one column per series.

As a reminder, kpiNumber and gauge ignore seriesProperty, since they only display single-values.

4.1. Use low-cardinality series only

I repeated this in every widget post but it is worth restating: seriesProperty should be low-cardinality. A property with five distinct values produces a readable multi-series chart. A property with two hundred values produces a colored mess. In that case, you might want to use a groupByRange, to reduce the amount of groups and therefore the series.

4.2. includeEmptyResults in multi-series

In single-series mode, includeEmptyResults: “Yes” fills empty time buckets with zero values. In multi-series mode, it does the same across both dimensions: every series gets a zero in any bucket where it has no data. This avoids broken lines and visually confusing gaps.

The behavior also adds a (none) bucket for objects whose primary group property has no value, and a (none) series for objects whose series property has no value. These are appended at the end so it doesn’t disrupt the “main story”.

4.3. Multi-select lookups in seriesProperty (and propertyName)

A subtle but important case: as you probably know, M-Files has a multi-select lookup property type. These allow the selection of multiple pre-defined values. Because of that, objects with multiple values will end-up in multiple buckets/groups, with the “counted once per value” rule.

Example: a customer with office locations in Geneva, Zurich and Berlin could appear three times, once for a Geneva bucket, once for a Zurich bucket and finally once for a Berlin bucket. The total of all bucket counts can therefore exceed the total number of objects when some objects have multiple values.

This is the correct and expected behavior for multi-select lookups. The alternative (counting each object only in its first value) would silently hide the multi-value relationships that often matter most.

5. displayProperties on drill-through

I mentioned displayProperties in section 2.5 above, as optional column to be added for list aggregations. The same field has a second role for all other aggregation type (summary, groupByProperty, groupByDateBucket, groupByRange): it controls the columns in the drill-through modal.

"aggregation": {
  "type": "groupByProperty",
  "propertyName": "Agreement type",
  "displayProperties": ["Effective through", "Responsible person"]
}

When the user clicks a donut slice (or a bar, or a row in a count table), the drill-through modal shows one row per object in that group, with the object name plus all the optional columns defined in the displayProperties value (e.g. Effective through and Responsible person).

6. The compatibility cheat sheet

I already put this table at the end of Post 4c, but it is short enough, so:

Combine this with the reducer table in section 3 and you have the full answer to “can I use aggregation X with widget Y, and with reducer Z on property type T”. In any case, the Visual Designer and the validation process will prevent you to make any mistake.

7. What this gives you

The query side (Post 5) plus the aggregation side (this post) together cover everything the engine supports. If that wasn’t the case before, you should now be able to read and understand every line from any of the previous JSON example.

The combinations are richer than they look at first. A groupByDateBucket on monthly invoices with a sum reducer on Amount and a seriesProperty on Customer, rendered as a line widget with includeEmptyResults: “Yes”, gives a multi-customer revenue trend that takes about 15 lines of JSON. A groupByProperty on Agreement type with a seriesProperty on Workflow state rendered as a table gives a cross-tab pivot with drill-through on every cell.

The possibilities aren’t endless, obviously, but good luck if you would like to try them all… Last time I checked, you could create several million different widget combinations. An important part of that would trigger warnings or errors for non-supported cases, but still a considerable scale.

So far, I covered the end-user part, the JSON, the widgets and now the queries. These are the building blocks of dashboards. The remaining posts of the series will cover:

• Post 7 – The Admin tab: the actions, Visual Designer / JSON editor, the two-stage validator, import / export, access control.
• Post 8 – Building a dashboard with the Visual Designer.

Want to know more about this Business Dashboard? Contact us and we will be happy to showcase it on M-Files.

L’article M-Files BD – Aggregations, reducers and series est apparu en premier sur dbi Blog.

A query has four parts: objectType, class, filters, and aggregation. This post covers the first three. The fourth (aggregations, including its reducers) is the topic of the next post.

As mentioned before, the principle that drove the design of the Business Dashboard is to be generic. The engine never enumerates specific business values, it only translates the structured JSON query into a standard M-Files server search.

1. objectType – the M-Files object type to query

Every query starts with objectType. It is the M-Files object type the engine searches against, addressed by its display name (the singular form is fine, the engine resolves it and uses it).

1.1. Single object type

The simplest form is a string:

"objectType": "Document"

Or any other object type defined in your vault:

// Looking for Customers
"objectType": "Customer"

// Looking for Projects
"objectType": "Project"

// Looking for Employees
"objectType": "Employee"

The display name is case-insensitive but must otherwise match what the vault shows. Please note that, if the vault is let’s say, in German, you might need to use “Dokument” and not “Document”. In short, you need to use what the vault defines/shows.

If the name does not match, the widget shows a clear ✗ Object type ‘xxx’ not found in this vault error.

1.2. Multiple object types

When the same logical entity exists across more than one M-Files object type (for example, a “Proposal” can be both a Document and a Document collection), you can pass an array:

"objectType": ["Document", "Document collection"]

The engine resolves every name and builds a single search to find all matching objects. This behaves like the “is one of” filter in M-Files Advanced Search. Please note that the Drill-through will also inherit the same scope, automatically.

A small but important detail: even in this case, the engine executes a single search. This matters for performance and for consistency (a single serverScanMaxResults cap applies, not two independent caps).

2. class – narrowing the scope (and the perf impact)

The class field is optional but strongly recommended. It restricts the query to one specific class:

"objectType": "Document",
"class": "Contract or Agreement"

Querying “all Documents” in a vault that contains 50’000 documents of which only 1’000 are Contracts is pure waste. Adding “class”: “Contract or Agreement” narrows the scan immediately, which both improves performance and makes the widget result more meaningful.

Therefore, both M-Files Administrators and M-Files Users will thank you for selecting the right class to use. It avoids slowness, irrelevant results and reduces resource usage. You should always set a class, when possible.

When objectType is an array and class is specified, the engine will find any object, from that class, from any of the object types listed. So the following will match Proposal-class objects from both types:

"objectType": ["Document", "Document collection"],
"class": "Proposal"

If the class is misspelled, the widget shows a ✗ Class ‘xxx’ not found on the specified object type(s) error. As with object types, the name depends on what the vault defines/shows.

3. filters – the AND-combined conditions

The filters array, which is optional, contains zero or more conditions. If you specify multiple filters, then all filters must match. That means that M-Files applies a AND semantic between each filter. By the way, M-Files doesn’t directly support “OR” conditions, it always joins them. The only “kind-of-an-exception”, as far as I know, is the “is one of” where you can set multiple values from the Lookup/MultiSelectLookup property values. But that’s only a single condition, not multiple conditions.

Here is an example of a filter:

"filters": [
  { "property": "Effective through", "operator": "greaterOrEqual",
    "value": "@today", "valueType": "dateToken" },
  { "property": "Agreement type", "operator": "equals",
    "value": "Subcontracting Agreement" }
]

Each filter has up to four fields:

• property: the property display name on which to apply the operator / value.
• operator: one of the operators listed in section 4 below.
• value: the value to use for the comparison with the property’s actual value. For the four “presence” operators (isEmpty, isNotEmpty, isPresentEmpty, isPresentNotEmpty), this parameter should NOT be defined. For the “begin-end” operators (between / notBetween, this parameter should be an array of two elements. For the “is one of” operators (inList / notInList), this parameter should be an array of at least two elements. Finally, in all other cases, it’s simply a string.
• valueType: either “literal” (default, it means to use the value as-is) or a “dateToken” (covered in section 5).

4. The filter operators

The engine supports a rich set of operators across two execution paths:

• Native: runs server-side before the serverScanMaxResults cap is applied. Therefore, this is the preferred option, when possible.
• Post-filter: runs in memory after the server returns up to serverScanMaxResults objects. Therefore, this is correct and useful when you want to do something that M-Files doesn’t support out-of-the-box but that still makes sense for your Business use-case.

In short, whenever possible, prefer to apply a native filter. The main reason for this is simple. Let’s assume that you have 1’000 Contracts in the vault:

• If you apply a native filter, for example Effective through >= @today, then if only 200 of them match that criteria, then M-Files will only return these 200 objects directly. There is no loss of performance here.
• If you apply a post-filter, for example Effective through contains 2026-12, then M-Files will have no other choice than returning all 1’000 Contracts first. On top of that, the post-filter compares the value of Effective through and checks whether it contains “2026-12”. This is because the “contains” condition doesn’t exist in M-Files for Date properties. Therefore, we cannot use what doesn’t exist, but we still want to provide that possibility / logic, and therefore it is done in memory after returning all results. In that example, you get 5x more results and on top of it, you also need to check which ones match the expected value.

The performance difference between native and post-filter is imperceptible for small result sets (<few hundreds), but you would probably feel it if you expect to fetch thousands of results. A great catch, if you need to apply a post-filter for a valid business reasons, is to first apply a native one, which highly reduces the result set, and then apply the post-filter one that you need. Also, don’t forget to specify a class!

Then, let’s proceed with a deep-dive on the different operators (if you only want the “summary”, look at the end of section 4 for the cheat sheet). The 22 operators support all data types, without exceptions, contrary to M-Files operators which offer much less capabilities. The only distinction is, as mentioned above, whether the operator is native or post-filter.

4.1. equals and notEqual

As you would expect, these are for exact match. Only the MultiLineText properties are processed as post-filter.

{ "property": "Agreement type", "operator": "equals",
  "value": "Subcontracting Agreement" }

{ "property": "Customer", "operator": "notEqual",
  "value": "ESTT Corporation (IT)" }

When using display names on Lookup properties (Lookup or MultiSelectLookup), as its the case in above example, the value lists are cached, so that each execution doesn’t need to re-fetch the things that it already knows of, and it can just use it directly, to ask M-Files what’s the updated count.

4.2. lessThan, greaterThan, lessOrEqual, greaterOrEqual

These “range” operators support all property types except Boolean, because it doesn’t make any sense to apply a “lessThan” to a Boolean… In addition, and similarly to above, only the MultiLineText properties are processed as post-filter, everything else is native. Obviously, you can apply these operators on Date and Numeric values, but it also works with Text, Lookup or MultiSelectLookup. When it needs to work on Text-based properties, it does a lexicographic comparison (e.g. ABC < ABD, ACE > ABB).

{ "property": "Due date", "operator": "lessThan",
  "value": "@today", "valueType": "dateToken" }

{ "property": "Amount", "operator": "greaterOrEqual", "value": 1000 }

4.3. between and notBetween

These as also “range” operators but I put them separately because the value must be a two-element array, as previously written. between is, otherwise, exactly the same as lessThan/greaterThan/lessOrEqual/greaterOrEqual. In the array, you would provide the begin and the end of the range. to fetch.

{ "property": "Effective through", "operator": "between",
  "value": ["@startOfYear", "@endOfYear"], "valueType": "dateToken" }

{ "property": "Amount", "operator": "between", "value": [100, 1000] }

notBetween is the opposite of between, obviously, but it’s a bit more than that… As previously mentioned, M-Files does NOT handle OR logic. But if you think about it, a “notBetween” is actually an OR, because you want values below the range OR above the range (value < low OR value > high). Because of that, notBetween is always a post-filter, without exception.

{ "property": "Amount", "operator": "notBetween", "value": [100, 1000] }

4.4. isEmpty, isNotEmpty, isPresentEmpty, isPresentNotEmpty

These four operators test whether a property has a value, as the name suggests… However, there is a catch: M-Files only distinguish between “the property is present and empty” or “the property is present and non-empty”.

You might have faced that with Templates for example. That’s a pretty common occurrence. In M-Files, there is a parameter “Is template” which indicates whether a specific object has been defined as a template. But that parameter is only present in a few select objects, it’s usualy not present on all of them. Therefore, if you search for “Is template – is empty”, you will most probably find 0 results, because M-Files only check for documents where the property is present and where it is empty.

The distinction is simple but it matters a lot. That’s why in the Business Dashboard, the native M-Files “is empty” / “is not empty” have been renamed as isPresentEmpty and isPresentNotEmpty. These are the fully native option from M-Files, and therefore they run on the server-side.

{ "property": "Effective through", "operator": "isPresentEmpty" }

{ "property": "Responsible person", "operator": "isPresentNotEmpty" }

In addition, I also defined two other operators, isEmpty and isNotEmpty. These two are always post-filters, they scan all matching objects in memory after the server returns them:

{ "property": "Effective through", "operator": "isEmpty" }

{ "property": "Responsible person", "operator": "isNotEmpty" }

Because of that post-processing, isEmpty matches objects where the property is absent OR where it is present but empty. This allows a more “complete” result set, which might be required in some specific business use-cases.

isNotEmpty matches objects where the property is present AND non-empty. You might think it is exactly the same as isPresentNotEmpty, right? Well, in 99% of the cases, yes it is the same (but slower, since done as post-filter)… Except when there are bugs in M-Files ;). While developing the Business Dashboard, I found a few bugs, including one with lexicographic processing on MultiSelectLookup properties. The usage of my own operator was giving me a slightly different result and while investigating why, I found the reason and the bug in M-Files’s own operator.

In summary:

4.5. inList and notInList

As the name suggests, if you are looking for multiple values, inList is what you should use. It must be an array of at least 2 elements, but you can put 50 if you want to. M-Files only support Lookup for this one, natively. Therefore, all other property types are handled as post-filters.

{ "property": "Agreement type", "operator": "inList",
  "value": ["Subcontracting Agreement", "Project Agreement"] }

{ "property": "Workflow state", "operator": "inList",
  "value": ["In review"] }

notInList is simply the opposite, so it just excludes all elements provided. It supports exactly the same thing as inList and works in the same way too.

{ "property": "Workflow state", "operator": "notInList",
  "value": ["Approved"] }

A subtle catch with “not” operators (notInList and similar): an object whose Lookup property is present but has no item selected satisfies “not in list” by default, because there is no value to match or compare with. If you don’t want to see these objects, then you can simply add a second filter on that same property with isPresentNotEmpty!

4.6. contains and doesNotContain

contains is a substring match (similar to matchesWildcardPattern (c.f. below) with implicit wildcards on both sides), it finds objects where the property value includes the given string anywhere inside.

{ "property": "Title", "operator": "contains", "value": "NDA" }

{ "property": "Title", "operator": "doesNotContain",
  "value": "draft" }

For Text, MultiLineText and Lookup properties, both operators are native. The rest is supported as post-filters, comparing against the string representation.

4.7. startsWith, doesNotStartWith, endsWith, doesNotEndWith

startsWith and doesNotStartWith match objects based on the beginning of a property’s value. These are native only for Text and Lookup properties.

{ "property": "Name or title", "operator": "startsWith",
  "value": "PO-"    }

{ "property": "Name or title", "operator": "doesNotStartWith",
  "value": "DRAFT-" }

endsWith and doesNotEndWith match based on the end of a property’s value. This doesn’t exist in M-Files, there is no equivalent and therefore, these are always post-filters for all property types.

{ "property": "Name or title", "operator": "endsWith",
  "value": "(final)" }

{ "property": "Name or title", "operator": "doesNotEndWith",
  "value": "(draft)" }

4.8. matchesWildcardPattern and doesNotMatchWildcardPattern

These are the most expressive pattern operators. The value is a regex string where \* matches any number of characters and ? matches exactly one character. This is pretty similar to the contains/startsWith/endsWith (and their opposite), obviously, but it is a bit more powerful if you need to match an exact pattern that you know of.

{ "property": "Title", "operator": "matchesWildcardPattern",
  "value": "PO-????-2026" }

{ "property": "Title", "operator": "doesNotMatchWildcardPattern",
  "value": "ID-*" }

4.9. Complete operator reference

You reached this point, so it’s time to have a cheat sheet of all operators. In the below table:

• Text and MultiLineText are NOT interchangeable
• “Lookup” includes both Lookup and MultiSelectLookup (these ARE interchangeable – one exception for between on MultiSelectLookup because of a bug in M-Files – the one I mentioned above)
• “Date” includes Date, Time and Timestamp (these ARE interchangeable – one exception for notEqual on Timestamp because of a bug in M-Files – not the same as the one mentioned above)
• “Numeric” includes Integer, Integer64 and Floating (these ARE interchangeable) (“integer”/”real”)

4.10. Pattern operators on date properties

All pattern operators (contains, startsWith, endsWith, matchesWildcardPattern and their negations) work on date properties via the post-filter path, comparing against the ISO yyyy-MM-dd string representation (or yyyy-MM-dd HH:mm for timestamp or HH:mm:ss for time properties). This opens up some convenient patterns, even with “valueType”: “literal”:

{ "property": "Effective through", "operator": "startsWith",
  "value": "2026" }

{ "property": "Effective through", "operator": "startsWith",
  "value": "2026-04" }

{ "property": "Effective through", "operator": "endsWith",
  "value": "-31" }

{ "property": "Effective through", "operator": "matchesWildcardPattern",
  "value": "2026-??-??" }

And with “valueType”: “dateToken”, the token resolves to a full ISO date used as the exact string pattern:

{ "property": "Effective through", "operator": "contains",
  "value": "@today", "valueType": "dateToken" }

{ "property": "Effective through", "operator": "startsWith",
  "value": "@startOfMonth+5d", "valueType": "dateToken" }

A resolved token produces a full ISO date for the operators, c.f. next section for a deeper dive into dateToken details.

5. Date tokens – relative filters that always make sense

Hardcoding a date like “2026-01-01” in a filter works, but it ages badly. The dashboard built today shows different data on January 2nd than it did on December 31st, because the filter is now relative to a different “today”.

Date tokens solve this. Any string value used with “valueType”: “dateToken” is resolved to an absolute date at query execution time, so the dashboard stays meaningful as time passes.

5.1. Anchor tokens

The following anchors are recognized:

So @startOfYear, at the time of writing this blog (i.e. in 2026) is 2026-01-01 00:00:00. Starting from January 1st 2027, the same token will automatically resolve to 2027-01-01 00:00:00 instead. Therefore, the dashboard rolls forward automatically.

If there is a need to add more date tokens, it’s always possible.

5.2. Offsets: days, hours, minutes, and seconds

Any anchor presented above can be followed by one or more offsets to add or subtract time:

Each offset uses d for days, h for hours, m for minutes, and s for seconds. As you can see above, offsets can be chained together in any order, so @today+2d+10h+30m is valid, as is @now-8h+30m.

The day offset is calendar days, not business days. There is no built-in concept of holidays in the engine as of now.

5.3. Fixed ISO dates (with optional offset)

A literal ISO date works as both literal as well as a date token. However, if you want to apply an offset, then only dateToken can be used. As previously mentioned, “literal” really means a literal strings, so there is no computation done on it.

{ "property": "Effective through", "operator": "greaterOrEqual",
  "value": "2026-01-01+90d", "valueType": "dateToken" }

This resolves to 2026-04-01 00:00:00, at query time. This can be useful when you want a stable absolute anchor but with an offset relative to it.

5.3a. When to use @now instead of @today

The key difference between @now and @today is that @now captures the current time including hours, minutes, and seconds, while @today is truncated to midnight.

Use @today for day-level filters (most common): “contracts expiring within 30 days”, “documents created this month”. Use @now when you need intra-day precision: “events logged in the last 2 hours”, “tasks to process in next 4 hours”. Examples:

// All activity since this morning at 7am (a fixed time each day)
{ "property": "Modified", "operator": "greaterOrEqual",
  "value": "@today+7h", "valueType": "dateToken" }

// Flagged tasks created in the last 8 hours
{ "property": "Created", "operator": "greaterOrEqual",
  "value": "@now-8h", "valueType": "dateToken" }

6. Boolean filter values

For boolean-typed properties (M-Files “Boolean (yes/no)”), the engine accepts both “Yes” / “No” and “True” / “False” (case-insensitive):

{ "property": "Accepted", "operator": "equals",
  "value": "Yes" }

{ "property": "Accepted", "operator": "equals",
  "value": "True" }

“Yes” / “No” is the preferred form because that is what M-Files displays in the UI and what users see in their property cards. Worth noting: the M-Files Admin label “Boolean (yes/no)” is always English even on a localized vault. So you do not need “Ja” / “Nein” mappings on a German vault (at least as of today).

7. Wrap-up

The query model covers the questions that come up in practice. objectType and class define the scope, filters narrow it with a rich set of operators spanning native server conditions and post-filter cases. Date tokens make filters relative without effort.

What is not in this post: the aggregation block. That is the topic of Post 6, which covers the aggregation types, the reducers, and the multi-series seriesProperty feature. Once those are explained, every JSON block in the widget posts will make complete sense.

Want to know more about this Business Dashboard? Contact us and we will be happy to showcase it on M-Files.

L’article M-Files BD – Queries: objectType, class, filters, date tokens est apparu en premier sur dbi Blog.

The grouping is loose but useful: donut and bar answer questions like “how does my population break down into categories?”, while table can answer pretty much any question… Together, they cover the rest of the use cases, where you want either a visual distribution or the actual details of what is in the vault.

1. donut – distribution across categories

The donut chart shows how a population splits across the distinct values of a property. Labels and values appear on the slices, while the legend is placed next to the donut when the pane is wide enough (otherwise below it). The engine computes a layout that estimates the legend width from the longest label, then centers the donut in the remaining space, with the ring filling the main part of the available area.

{
  "id": "",
  "title": "Contracts by Agreement Type",
  "type": "donut",
  "gridColumnSpan": 6,
  "gridRowSpan": 2,
  "query": {
    "objectType": "Document",
    "class": "Contract or Agreement",
    "aggregation": {
      "type": "groupByProperty",
      "propertyName": "Agreement type",
      "includeEmptyResults": "No"
    }
  }
}

1.1. Aggregations the donut accepts

Three aggregation types work with donut:

• groupByProperty: group by the values of that specific property, often the natural choice for category distributions.
• groupByDateBucket: group by dates based on a certain bucket size. The date buckets will be ordered chronologically, where usually donut slices would be ordered by decreasing counts of objects.
• groupByRange: group by manually defined range of things (string, number), often the natural choice for large set of values (e.g. revenues)

1.2. resolveValueListLabels

For properties backed by an M-Files value list, resolveValueListLabels: “Yes” (the default) shows the human display names on the slices’ tooltip and in the legend. On the other hand, “No” shows the internal IDs. The default is correct for almost every dashboard, “No” might be useful for technical investigations. That’s why this field isn’t show in the Visual Designer, to avoid issues. If you want to set it, you will need to do it from the JSON editor directly.

1.3. seriesProperty: the multi-mini-pie grid

This is the most distinctive feature of the donut widget. When you set a seriesProperty, the widget switches to a multi-mini-pie grid: one donut per distinct value of the series property, all sharing a single legend. Each small donut shows the distribution of the primary propertyName within that series slice.

{
  "id": "",
  "title": "Contracts by Agreement Type x Year",
  "type": "donut",
  "gridColumnSpan": 12,
  "gridRowSpan": 4,
  "query": {
    "objectType": "Document",
    "class": "Contract or Agreement",
    "aggregation": {
      "type": "groupByDateBucket",
      "propertyName": "Effective through",
      "bucketSize": "year",
      "seriesProperty": "Agreement type",
      "includeEmptyResults": "No"
    }
  }
}

This produces, for example, one donut per Agreement type, with each donut showing the distribution by year for their Effective through property. As you can see below, it takes more space, since multiple donuts will be displayed. Depending on what you want to see, you could also simply display multiple donut widgets with the associated filters, instead of a single widget with a multi-series. That is, if you know how many series you need (and therefore how many widgets you need with their dedicated filters) and if it’s not a dynamic number.

A few practical notes:

• The donuts are all resize-aware: when the right pane is resized, the engine recomputes the size of all donuts. The number of donuts per row is fixed and defined at first rendering, based on the size that the widget has available (based on its configuration) and the number of series that were found.
• A series where every visible slice is zero is shown as a grey ring, so the user does not have to wonder whether the chart loaded. This is the same for single-series donuts too.
• Like every seriesProperty, this should be a low-cardinality property. A grid of six donuts is most probably fine, but a grid of fifty might be difficult to display properly, unless if you have a very big screen!

1.4. The tooltip touch

As all other tooltips, the one on the Donut will show the numbers that match the query with a thousand separator (e.g. 1’520 or 1,520 (depending on your regional settings) rather than 1520). But in addition, it will also include the percentage that this slice represents. It is a small detail, but it usually helps and avoids the need to calculate that yourself.

2. bar – vertical and horizontal bar charts

The bar widget covers a large surface and deserves its own deep dive. It supports both vertical and horizontal orientations, both single-series and multi-series modes, and per-bar threshold coloring in single-series too. Most of the configuration lives in two display keys: barLayout and thresholds.

2.1. A first vertical bar

Taking the same example as for the previous blog post on the Invoices/Revenue:

{
  "id": "",
  "title": "Monthly revenue",
  "type": "bar",
  "gridColumnSpan": 12,
  "gridRowSpan": 2,
  "query": {
    "objectType": "Document",
    "class": "Invoice",
    "filters": [
      { "property": "Invoice date", "operator": "between",
        "value": ["@startOfYear", "@endOfYear"], "valueType": "dateToken" }
    ],
    "aggregation": {
      "type": "groupByDateBucket",
      "propertyName": "Invoice date",
      "bucketSize": "month",
      "reducer": "sum",
      "reducerProperty": "Amount",
      "includeEmptyResults": "Yes"
    }
  }
}

The X-axis labels rotate at -15 degrees always (not conditionally), so they never overlap the bars or the chart area below them. This was a small thing needed to avoid strange display when the space for the widget is very small or when there are long labels to be displayed. As you can see below, it is very similar to the line/area widgets in its essence:

2.2. display.thresholds in single-series mode

In single-series mode, display.thresholds colors each bar individually based on its own value. You can either use text values representing colors or the HTML color code:

"display": {
  "thresholds": [
    { "value": 0, "color": "red" },
    { "value": 40000, "color": "orange" },
    { "value": 100000, "color": "yellow" },
    { "value": 120000, "color": "green" }
  ]
}

So bars with value 0 to 40’000 will be displayed in red (when value is 0, there is no bar, so only the tooltip will show a red “0”). Bars with 40’000 to 100’000 will become orange, etc.:

As with line / area, thresholds are ignored in multi-series mode (each series uses the automatic palette so the legend color stays consistent).

2.3. display.barLayout

Bar charts have two orthogonal choices: orientation (vertical vs horizontal) and multi-series mode (stacked vs grouped). The display.barLayout key combines them into a single value:

For single-series bars (i.e. when no seriesProperty is used), only orientation matters. The stacked / grouped distinction has no visible effect, since there is a single value anyway). So a single-series chart with vertical-stacked and one with vertical-grouped render identically.

Horizontal charts place categories on the Y axis (top to bottom in the same order they would appear left to right on a vertical chart) and values on the X axis. This is useful when category labels are long enough that the -15 degree rotation still does not fit or when you want more space to display the values rather than the different categories.

See the screenshot on the following section for the distinction between the vertical/horizontal and stacked/grouped.

2.4. seriesProperty: stacked or grouped

"aggregation": {
  "type": "groupByDateBucket",
  "propertyName": "Invoice date",
  "bucketSize": "month",
  "reducer": "sum",
  "reducerProperty": "Amount",
  "seriesProperty": "Country",
  "includeEmptyResults": "Yes"
}

With seriesProperty: “Country” and display.barLayout: “vertical-stacked”, you get a stacked bar chart where each month bar is split into each values found for the “Country” property (here: Switzerland & USA). With vertical-grouped, you get two side-by-side bars per month (one for each “Country” value). The chart tells the same story with two (or rather four) different displays. Note: for the below screenshot, I reduced the filtering to only the first 6 months of the year, to be able to do a side-by-side comparison of how these charts look. The goal isn’t to see the full year here, only to show you how these different display options render:

2.5. Aggregations the bar widget accepts

The bar widget accepts groupByProperty, groupByDateBucket and groupByRange, same as the donut and trend widgets, and the date-valued reducer rule from posts 4a and 4b applies here too: a reducer that returns a date string cannot be plotted on a numeric axis, so the widget will show a placeholder.

3. table – sortable, paginated, multipurpose

The table widget is the last, and most flexible of the catalog. It accepts all five aggregation types (summary, groupByProperty, groupByDateBucket, groupByRange, list), and it is the only widget that supports list. This makes it the natural fallback when other widget types cannot display a specific combination, and the obvious choice when the user wants to see the raw objects (without the drill-through).

3.1. A list-aggregation table

This is the “give me the details” case. The aggregation is list and with the displayProperties parameter, it is possible to control which columns are shown alongside the object name.

{
  "id": "",
  "title": "All Projects",
  "type": "table",
  "gridColumnSpan": 12,
  "gridRowSpan": 4,
  "query": {
    "objectType": "Project",
    "aggregation": {
      "type": "list",
      "displayProperties": ["Class", "In progress", "Customer", "Project Manager"]
    }
  }
}

The result is a sortable table with one row per Project, and five columns (object name, Class, In progress, Customer and Project Manager). Above, there was no Class enforced, so all classes from M-Files will apply. That’s why in the screenshot, you can see both Internal Project and Customer Project objects, which are the two classes in question. Only the Customer Project has a Customer property, but it isn’t a problem, it is simply displayed as “-“ for the Internal Project objects. Clicking a row name navigates the user directly to the object in M-Files, no drill-through modal is opening, since the row already represents one object.

3.2. Sorting and pagination

Every column header is clickable to sort ascending or descending. In above screenshot, the second column is sorted in descending order. The sort applies across all fetched rows, not just the currently visible page, which (I believe) is the behavior users would expect when sorting.

Note: This is NOT how M-Files behaves in its own search! In M-Files, by default, when you search for something and you get more than 1 page of results, if you sort a column, only what is displayed on the screen gets sorted… Which is a problem from my point of view, since it sorts only partial data and you might see things you don’t expect. Therefore, M-Files is doing a page-by-page sorting and not a global sorting. On the other hand, the Business Dashboard will sort correctly and apply the sorting on ALL data, and not just the current page.

Pagination kicks in at 15 rows per page, by default (configurable), and the pagination bar at the bottom shows the current range and the total fetched.

3.3. Display details

Numeric columns honor display.decimals and both numeric and dates honors regional settings as well. In above example, you can see the 4th row with a Customer column that shows a value “Tennessee Land Surveyors (Nashville) || Lance Smith Engineering (Surveying)”. This is actually a concatenation of two customers. This project, in the M-Files Sample Vault, is assigned to two different customers, and therefore, it is shown in the table (or any drill-through modal) as a concatenation of Customer1 || Customer2. No data is silently cut or hidden, everything that is actually part of the metadata model is shown as it should. That’s how multi-select lookup values are displayed.

3.4. seriesProperty: the cross-tab pivot

As other widgets, the table supports multi-series (via the same seriesProperty) when it is using a groupByProperty, groupByDateBucket or groupByRange aggregation. In this case, it becomes a cross-tab pivot. This means that rows will remain the groups for the primary group property, while additional columns will be added for each group of the series property. Therefore, both rows (primary group) and columns (series group) are fully dynamic. Here are two table widgets definitions, the first one without multi-series and the second one with it:

"aggregation": {
  "type": "groupByProperty",
  "propertyName": "Project manager",
  "displayProperties": ["Class", "In progress", "Customer", "Project Manager"]
}
...
...
"aggregation": {
  "type": "groupByProperty",
  "propertyName": "Project manager",
  "seriesProperty": "Class",
  "displayProperties": ["Class", "In progress", "Customer", "Project Manager"]
}

With the above, you get the count of Projects that each Project Manager handles for the first one. While the second widget, adds another dimension that is the “Class” of the objects, i.e. whether the Projects that the managers handle is an Internal Project or a Customer Project. The result of these two widgets is the following:

In this multi-series case, all series columns include a link on their count. Therefore, each number is clickable, and it will display the drill-through that matches this series AND this primary group. E.g. which Customer Projects are handled by Tommy Hart.

3.5. Drill-through on tables

Table drill-through behavior depends on the aggregation type, which is documented in detail in Post 2 (the end-user post) but worth recapping here:

• For summary, groupByProperty, groupByDateBucket or groupByRange: clicking a row (or a specific column from a row in case of multi-series as mentioned above) opens the drill-through modal showing the underlying objects.
• For list: clicking a row name navigates directly to the object. No modal, because the row already represents one object.

3.6. The “safe fallback” role

I mentioned earlier that table accepts every aggregation type. This makes it the safe choice for cases where other widgets refuse. The most common one is date-valued reducers: if the answer to your question is a date per group (e.g. “latest invoice date per customer”), the chart widgets cannot plot that, but the table widget will happily render it with one row per customer and a date value for each row.

Whenever the validation flags a date-valued reducer warning on a chart widget, switching the widget type to kpiNumber or gauge might be the right answer if you need only one date. Otherwise, switching to table is the only remaining and valid option.

4. The compatibility cheat sheet

To close the widget posts, here is the full compatibility matrix the validator enforces, as of now. You can use that as a quick reference when authoring:

When the validation reports an incompatible combination, the message usually includes the right alternative (typically “use kpiNumber, gauge or table” for date-valued reducers, or “use table for list aggregations”).

5. Closing thoughts

That closes the widget catalog. The seven widget types cover the full range of business questions I typically see: scalar answers (kpiNumber, gauge), trends (line, area), distributions (donut, bar), and raw enumerations or whatever else (table).

Two observations from real customer dashboards:

• Most useful dashboards mix widget types. A row of KPIs at the top, a couple of distribution charts in the middle, a list table at the bottom. The mental model the user builds reading top to bottom is “summary, distribution, details”.
• Most pitfalls live at the boundary between aggregation and widget type. If a widget shows a placeholder, the explanation is almost always “this aggregation produces a shape this widget cannot render”. The validation spells it out before save, so trust it.

Post 5 shifts from “what widgets exist” to “how to write the query that feeds them”: object types, classes, filter operators, and date tokens. After that, Post 6 covers aggregations and reducers in detail. With those two, every JSON block in the widget posts will make complete sense.

Want to know more about this Business Dashboard? Contact us and we will be happy to showcase it on M-Files.

L’article M-Files BD – Distribution and tabular widgets: donut, bar, table est apparu en premier sur dbi Blog.

1. Why these two are in the same post

The wire format and the rendering pipeline for line and area are nearly identical. They produce the same JSON on the server, they use the same client code path, they accept the same aggregation types, the same reducers, the same display options. The only meaningful difference is visual: area fills the region under the line with a translucent color, while line leaves it transparent.

In other words: choose area when you want to emphasize cumulative volume or magnitude, choose line when you want to emphasize the trajectory. Both communicate the same thing, it’s more about what you want to focus on.

2. A first example: monthly revenue trend

Here is the canonical example: total invoice amount per month for the ongoing year, displayed as a line chart.

{
  "id": "",
  "title": "Monthly revenue",
  "type": "line",
  "gridColumnSpan": 12,
  "gridRowSpan": 2,
  "display": { "smooth": "Yes", "decimals": 0 },
  "query": {
    "objectType": "Document",
    "class": "Invoice",
    "filters": [
      { "property": "Invoice date", "operator": "between",
        "value": ["@startOfYear", "@endOfYear"], "valueType": "dateToken" }
    ],
    "aggregation": {
      "type": "groupByDateBucket",
      "propertyName": "Invoice date",
      "bucketSize": "month",
      "reducer": "sum",
      "reducerProperty": "Amount",
      "includeEmptyResults": "Yes"
    }
  }
}

A few things to note in this JSON:

• The filter restricts the data to the current calendar year using two date tokens. The full date-token vocabulary is covered in the future Post 5.
• The aggregation is groupByDateBucket on the same date property, bucketed by month. Each bucket is reduced with sum of the Amount property. In other words, this means that all invoices with a date within this calendar year will be grouped by month and the value coming from the Amount property will all be summed within each month to arrive to a Total per month.
• includeEmptyResults: “Yes” ensures that months with no invoices appear as zero values, so the trend line is continuous from January to December rather than skipping empty months (e.g. you were closed for vacations or weren’t able to sell anything for some other reasons).

Switching the widget type from line to area in this exact JSON gives the area-chart variant, nothing else changes:

3. The aggregation types these widgets accept

line and area are valid with three aggregation types:

• groupByDateBucket: the natural fit for time series. It groups a date / timestamp property into a certain bucket: day, week, month, quarter, or year.
• groupByProperty: groups by the distinct values of any property. It supports date/time properties, but it’s uncommon, as each day would be a data-point. It also support any other type of properties, to display them as categorical trends (e.g. “Monthly revenue per region” rendered as a line for some reason). Depending on requirements, a bar display might be more adapted.
• groupByRange: define manual ranges of something (string or number) and turn them into points to plot (e.g. Revenue <1k, <10k, <50k, <100k, >=100k)

The visual designer will only allow you to select one of these three aggregations. But if you try to set a summary or list aggregation in the JSON editor directly, then an error will be thrown, as it isn’t possible.

4. display.smooth

The single most common display option for these widgets is smooth:

"display": { "smooth": "Yes" }

When set to “Yes”, the line/area charts draws a Bézier-smoothed curve between data points (c.f. example above). When “No” (or omitted), the connecting line is made of straight segments. Smoothing makes monthly or quarterly trends look more visually pleasant. It can also slightly hide outliers, so use it where the trend story is more important than the exact per-bucket value.

5. display.decimals

For numeric reducers (sum, avg, min, max, median), this controls how many decimal places are shown in tooltips (default 0).

"display": { "smooth": "Yes", "decimals": 2 }

In the monthly-revenue example above, if amounts are stored as floats (which is probably the case), you may want decimals: 2 so the tooltip would show 116’520.43 rather than 116’520.

6. display.thresholds in single-series mode

In single-series mode (no seriesProperty), the thresholds array colors each data point marker based on its own value. The connecting line (and the area below) itself stays brand blue. The configuration is the same as on kpiNumber and gauge. You can either use text values representing colors or the HTML color code:

"display": {
  "smooth": "Yes",
  "thresholds": [
    { "value": 0, "color": "red" },
    { "value": 40000, "color": "orange" },
    { "value": 100000, "color": "yellow" },
    { "value": 120000, "color": "green" }
  ]
}

This is useful to highlight specific buckets that crossed a business threshold without changing the overall trend visualization. As mentioned in Post 4a, the default falls back to brand blue for values below the lowest threshold.

7. seriesProperty: multiple lines on the same chart

This is where these widgets become genuinely powerful. When you set a seriesProperty on the aggregation, the engine produces one line per distinct value of that additional property, with an automatic legend and color palette.

For instance, splitting the monthly revenue line into separate lines per country:

"aggregation": {
  "type": "groupByDateBucket",
  "propertyName": "Invoice date",
  "bucketSize": "month",
  "reducer": "sum",
  "reducerProperty": "Amount",
  "seriesProperty": "Country",
  "includeEmptyResults": "Yes"
}

A few notes that matter in practice:

• display.smooth applies to every series. There is no per-series smoothing.
• display.thresholds are silently ignored in multi-series mode. If they were applied per-point, they would override the series palette colors and break the relationship between line color and legend label. So the engine drops them in multi-series and keeps the legend honest.
• includeEmptyResults in multi-series mode fills gaps across both dimensions (every series gets a zero in any time bucket where it has no data). This avoids broken lines.

7.1. Use low-cardinality series only

The seriesProperty is best used with low-cardinality properties: lookup values, booleans, short text ranges. A monthly revenue chart with 5-6 customers is readable, but the same chart with two hundred customers becomes a colored mess where no individual line is distinguishable from the others. If there are too many series, it loses its usefulness. The validation wouldn’t block it though, since it is technically a valid compatibility. Try it, and see what it looks like!

8. includeEmptyResults: gap filling

I mentioned this earlier already, and as you could see above, there are actually months with “0” values/amounts.

With includeEmptyResults: “Yes” present, the graph will fill the gaps between the earliest and the latest data points found with zero values. In above example, we can see in March that there was 0 revenue in total. And similarly, in October, there was 0 revenue for the USA. There is no discontinuity in the lines, all months are present, even if there is “0” as a result.

With includeEmptyResults: “No”, the chart will only display the buckets that have at least one matching object (across the series). So, if no invoice was issued in March, the X axis jumps from February to April directly. For above case, it would still display October, since there is a revenue in Switzerland, therefore the USA line will display a “0” value still, the line cannot be “cut”. Visually, that compresses the time scale and hides the meaningful “we had no revenue in March” signal.

There are valid use cases for both situations, so just select the one that makes sense depending on what you want to see.

Note: Adding includeEmptyResults: “Yes” can also add a (none) bucket for objects whose property used by the groupByProperty has no value. For example, if you group by a boolean state Yes/No, and some objects do not have a value on that boolean, they would end up in this (none) group. For groupByDateBucket or groupByRange, they usually appear less frequently since you are grouping things on a certain range, but in the end, it also behaves in the same way if it does happen.

9. The “no date-valued reducer” rule

Same rule as on chart widgets in general: line and area cannot render a reducer that returns a date string. If you write something like:

"aggregation": {
  "type": "groupByProperty",
  "propertyName": "Customer",
  "reducer": "max",
  "reducerProperty": "Invoice date"
}

Then, with a line widget, the display would contain a placeholder and the query validation would show a warning. The reason was discussed in the previous post: ISO dates cannot be plotted on a numeric axis at the moment, so it wouldn’t make sense as a display.

The workaround is the same: use kpiNumber or a gauge in date mode if you only want to display one value, or a table for one or more values.

10. Drill-through on trend widgets

When drillThroughEnabled is “Yes”, clicking a data point opens the drill-through modal with the objects in that bucket. In multi-series mode, the click respects the series the point belongs to: only objects matching both the time bucket and the series value are shown. This makes it easy to answer questions like “show me the May invoices from Switzerland” with a single click on the right point of the line.

11. Wrap-up

line and area are the natural choice for time-series questions. They are fundamentally one widget with two visual modes, sharing the same aggregation contract and the same display vocabulary. The interesting part is what you can do with seriesProperty: turning a single trend into a multi-actor comparison without writing any extra logic.

Post 4c picks up the remaining three widgets: donut, bar, and table. The grouping rationale will be that they all answer distribution questions (how a population breaks down by category) or tabular questions (give me the raw rows), as opposed to the time-trend questions that line and area handle.

Want to know more about this Business Dashboard? Contact us and we will be happy to showcase it on M-Files.

L’article M-Files BD – Trend widgets: line and area est apparu en premier sur dbi Blog.

• Scalar widgets: kpiNumber and gauge both display a single value (a count, a sum, a date) over the matching object set. This is what the current post covers.
• Trend widgets: line and area, which are very similar both in form and in configuration, will be the next post, 4b.
• Distribution and tabular widgets: donut, bar, table, which are all remaining supported widgets (as of now), c.f. Post 4c later.

The reason kpiNumber and gauge sit together is that they accept exactly the same aggregation type (summary) and they share the same reducer model. So once you understand one, the other is mostly a different visual.

1. The summary aggregation in one paragraph

A full post will be dedicated to aggregations (Post 6 in the series), but to make this one self-contained: the summary aggregation returns a single value over all the matching objects. By default, it counts all matching objects. Its initial name was actually “count”, but later I wanted to introduce mathematical capabilities (c.f. the next sentence) so I had to change the name. With a reducer of sum, avg, median, min, or max (instead of the default count), it reduces a property’s values across the matching set instead.

// Total count of matching objects
"aggregation": {
  "type": "summary"
}

// Sum of an "amount" property for all matching objects
"aggregation": {
  "type": "summary",
  "reducer": "sum",
  "reducerProperty": "Amount"
}

// Latest contract expiry date among all matching objects
"aggregation": {
  "type": "summary",
  "reducer": "max",
  "reducerProperty": "Effective through"
}

Both kpiNumber and gauge accept this aggregation and only this one. The validator’s compatibility matrix is strict on that point. If you ever try to put a groupByProperty (or something else) on a KPI tile, you will not be able to save your dashboard.

2. kpiNumber – the big number tile

The kpiNumber is the simplest widget in the catalog. It shows a large number, with an optional small unit label below.

Minimal example:

{
  "id": "",
  "title": "All Contracts",
  "type": "kpiNumber",
  "gridColumnSpan": 3,
  "gridRowSpan": 1,
  "query": {
    "objectType": "Document",
    "class": "Contract or Agreement",
    "aggregation": { "type": "summary" }
  },
  "display": { "unit": "contracts" }
}

2.1. display.unit

A small text label shown below the number (c.f. above screenshot), indicating the natural unit of the value: “contracts”, “invoices”, “CHF”, “open items” etc… This is purely optional, so you can omit it if the title is already self-explanatory.

2.2. display.decimals

Number of decimal to use for the widget (default 0). This is useful when the reducer isn’t the default count, since a count of object is mandatorily an integer. For example:

"display": { "unit": "CHF", "decimals": 2 }

2.3. display.thresholds

This one is where the KPI tile becomes really useful in management dashboards. The thresholds array colors the number based on the current value. You can either use texts representing colors or the HTML color code:

"display": {
  "unit": "Overdue Invoices",
  "thresholds": [
    { "value": 0,  "color": "green"   },
    { "value": 1, "color": "orange"  },
    { "value": 10, "color": "red" }
  ]
}

The engine applies the color of the highest threshold where currentValue >= threshold.value. So in the example above:

• 0 overdue invoices: green
• 1 to 9: orange
• 10 and above: red
• Below 0 (which would be unusual for a count, but possible for a sum on a money property): falls back to brand blue (#006eef – which can be changed with a configuration on Admin side) with the above example. But nothing prevents you to set a threshold on negative values.

Please note that thresholds apply only to numeric values. When the KPI shows a date (e.g. max on a date property), thresholds are ignored and the brand color stays. That’s the current behavior, and it might change if there is a need that calls for it.

2.4. Reducer types on kpiNumber

All six reducers are supported, with the standard property-type rules:

• count (default): count the number of objects and you do not need to specify the reducerProperty in this case, since it’s taken by default.
• sum, avg, median: numeric / time properties.
• min, max: numeric properties or date / timestamp / time properties.

A few real-world combinations:

// Count
{ "type": "summary" }

// Total revenue
{ "type": "summary", "reducer": "sum", "reducerProperty": "Amount" }

// Average duration
{ "type": "summary", "reducer": "avg", "reducerProperty": "Project duration days" }

// Latest contract expiry
{ "type": "summary", "reducer": "max", "reducerProperty": "Effective through" }

// Oldest open invoice
{ "type": "summary", "reducer": "min", "reducerProperty": "Invoice date" }

The last two return ISO date strings internally, which is then displayed on the end-user side as DD/MM/YYYY (or whatever matches your regional settings like MM/DD/YYYY in the US for example). So, in M-Files Sample Vault you can build a KPI like “Latest contract expiry: 31/12/2026” with three lines of JSON.

2.5. Drill-through on kpiNumber

When drillThroughEnabled is “Yes” at the dashboard level, the entire KPI tile is clickable. A click opens the drill-through modal with all the objects that contributed to the value. This is useful for all types of reducers, to get more details on how the dashboard reached that value.

3. gauge – the dial

The gauge is also driven by a summary aggregation, but it shows the value on a dial against a defined range. It comes in two flavors depending on the property selected for the reducer.

3.1. Numeric mode

This is the default mode and it can be used with any reducer: count, sum, avg, median, or min / max on a numeric property. The scale is in the natural units of the value, with display.min and display.max bracketing the dial.

{
  "id": "",
  "title": "Overdue Invoices",
  "type": "gauge",
  "gridColumnSpan": 6,
  "gridRowSpan": 2,
  "display": { "min": 0, "max": 50, "unit": "invoices" },
  "query": {
    "objectType": "Document",
    "class": "Purchase Invoice",
    "filters": [
      { "property": "Deadline", "operator": "lessThan",
        "value": "@today", "valueType": "dateToken" }
    ],
    "aggregation": { "type": "summary" }
  }
}

3.2. display.thresholds on a gauge

Same shape as the kpiNumber, but the gauge applies the colors to both the pointer and the arc segments, so the dial visually splits into zones:

"display": {
  "min": 0, "max": 50, "unit": "invoices",
  "thresholds": [
    { "value": 0, "color": "green"  },
    { "value": 5, "color": "orange"  },
    { "value": 20, "color": "red" }
  ]
}

This colors the arc as: 0 to 5 in green, 5 to 20 in orange, 20 and above in red. The pointer also takes the color of the zone where the current value lands. In other words, a glance at the dial tells you whether you are in a comfortable zone, a warning zone, or a critical one (c.f. above screenshot for the example with the colors).

3.3. Date mode

When the reducer is min or max and reducerProperty is a date / timestamp / time property, the gauge switches to date mode automatically. The dial then represents a day offset relative to today:

• display.min and display.max are, for date / timestamp properties expressed in day units, where 0 is today, negative values are in the past, positive values are in the future. For time properties, it is expressed in hours units, where 0 is midnight and 24 is, well, also midnight, but the next one ;).
• Graduation labels show dates like DD MMM if all dates are within a 365 timeframe, or it adds the YY if it goes beyond, so you know which date exactly we are talking about (depends on your regional settings). For time specifically, the graduation switch automatically to HH:mm display.
• The center detail shows the actual date DD/MM/YYYY (in your regional display preference) that comes from the reducer (again, it respects your date regional settings). Or DD/MM/YYYY HH:mm for timestamps or HH:mm:ss for time properties.

{
  "id": "",
  "title": "Closest Expiry",
  "type": "gauge",
  "gridColumnSpan": 6,
  "gridRowSpan": 2,
  "display": { "min": 0, "max": 180, "unit": "next expiry" },
  "query": {
    "objectType": "Document",
    "class": "Contract or Agreement",
    "filters": [
      {
        "property": "Effective through",
        "operator": "greaterOrEqual",
        "value": "@today",
        "valueType": "dateToken"
      }
    ],
    "aggregation": {
      "type": "summary",
      "reducer": "min",
      "reducerProperty": "Effective through"
    }
  },
}

In this example, the dial spans from today to 180 days in the future. If the earliest contract expiry is 22 days from today, the needle lands at the date that represents 22 and the center shows the actual date. If it is already in the past (negative offset), it indicates an overdue situation immediately. (in below screenshot, I’m using dates related to the past, as that’s what is available in the Sample Vault from M-Files, but in a real-world, the above JSON is usable)

3.4. When the reducer cannot produce a numeric value

If you try to use a date reducer on a chart widget (bar, line, area, donut), the widget will show a grey placeholder text, explaining that it is not supported (doesn’t really make sense). Moreover, before that, the administrator that designed the dashboard also got the same warning that this isn’t something that would work.

On a gauge, you have the date-mode escape hatch. On a kpiNumber or a table, the value is just formatted as a date string. So as a rule, date-valued reducers belong on kpiNumber, table, or gauge (date mode). They do not belong on chart widgets.

As said, this rule is not arbitrary, it is what the engine actually enforces. The “Test Widget”, “Test Queries” or “Save” will all tell you the same thing in a friendly way, if you slip or forgot about it.

4. Summary of reducers for scalar widgets

To close this post, here is a quick reference of what works on kpiNumber and gauge:

As described above, there is a subtle difference of “0” vs “-” for the empty results. For the default count, we display “0”, as there was really no objects returned, so the count of them is correct. For all other reducers, if there is no results, then there is nothing to do maths on. To differentiate between “no results” and “sum is really 0” (e.g. -2+2), I decided to display “-” for cases where there is no actual data to compute.

Of course, this empty results set difference is only true when there are no data returned. So if your filter is accurate and you expect some data, then it will never happen.

5. Closing thoughts

kpiNumber and gauge are the two widgets that typically stands at the top of a dashboard. It can be in a row of four KPIs and a gauge below, or side-by-side, depending on the layout defined. They give the at-a-glance answer that motivated the whole module in the first place.

In the next post (4b), I will talk about the trend widgets, line and area, which work in pairs almost as closely as kpiNumber and gauge do here.

Want to know more about this Business Dashboard? Contact us and we will be happy to showcase it on M-Files.

L’article M-Files BD – Scalar widgets: kpiNumber and gauge est apparu en premier sur dbi Blog.

Every dashboard is a single JSON document. The Admin tab in M-Files Admin offers a Visual Designer that builds this JSON for you, but in the end the JSON is the source of truth, so I think it is worth understanding its shape before getting into widget types and queries in the next posts. Think of this post as the reference map the rest of the series will refer back to.

1. The minimum valid dashboard definition

Before discussing every field, here is the (almost) smallest dashboard JSON that the engine accepts. It is intentionally trivial – a single KPI widget counting all Documents in the vault:

{
  "schemaVersion": 1,
  "id": "",
  "name": "My Dashboard",
  "widgets": [
    {
      "id": "",
      "title": "Total Documents",
      "type": "kpiNumber",
      "query": {
        "objectType": "Document",
        "aggregation": { "type": "summary" }
      }
    }
  ]
}

Note 1: Boolean-like fields are exposed as the strings “Yes” or “No”. This is what M-Files shows as booleans, don’t ask me why it’s not True/False like the rest of the world ;).

Note 2: Display names (object types, classes, properties, value-list items) must match what the vault shows in M-Files Admin. They are case-insensitive but must otherwise be exact.

2. The dashboard-level fields

The top-level object can carry the following fields: required ones are marked, all others are optional with default values that make sense, usually.

2.1. Identification and presentation

These are the main parameters of a dashboard that you will usually set at the beginning:

• schemaVersion: Integer (currently 1). The Business Dashboard validation process emits a warning when this field is absent or lower than expected. This version is incremented when breaking changes are introduced, so admins will automatically be flagged that they need to update something.
• id (required): typically a UUID v4 value (e.g. “12345678-abcd-1234-5678-abcd12345678”) but it isn’t restricted to that (e.g. “d01-contracts” works as well). The ID should be unique for each dashboard, otherwise you risk overriding an existing dashboard when you save. You can leave the field ID empty (as done above), the Business Dashboard will automatically generate one for you.
• name (required): Text shown in the end-user dropdown, you should keep it concise (<250 chars).
• description: Optional subtitle shown in italic below the top bar (hidden when absent). As described in the previous post, the first two lines will be shown on the user side, with a hover tooltip for the full text.

2.2. Auto-refresh

These are parameters that controls whether or not the dashboard will refresh itself or allows controls about the refresh more globally:

• autoRefreshEnabled: “Yes” or “No” (default “No”). Whether auto-refresh is enabled when the dashboard first loads.
• autoRefreshIntervalSeconds: Integer (default 300, minimum 15). Typical values can be 60, 300 or 900 for example. This is the interval of time between two auto-refresh of all widgets done when the auto-refresh is enabled (either via autoRefreshEnabled or because userCanToggleAutoRefresh is “Yes” and a user enabled it manually). The minimum is set to 15s to avoid overloading the vault in case of mis-configuration.
• userCanToggleAutoRefresh: “Yes” or “No” (default “No”). Whether the user can disable or enable the auto-refresh feature.

2.3. Exports and drill-through

These are the optional features that you can enable:

• exportToPdfEnabled: “Yes” or “No” (default “No”). Shows the ⎙ PDF button in the top bar, to allow users to export the dashboard to PDF.
• exportToCsvEnabled: “Yes” or “No” (default “No”). Shows the ⊞ CSV button on all widgets (except kpiNumber & gauge) as well as on the drill-through modal, to allow users to export the widget details to CSV.
• drillThroughEnabled: “Yes” or “No” (default “No”). Makes chart elements and rows clickable to open the drill-through modal (c.f. previous post if you don’t know what the drill-through is).

These three flags are intentionally off by default. Turning them on is an explicit choice per dashboard, which I think is the right place to make that decision. A dashboard meant for casual “at-a-glance” use might not need them while a dashboard meant for active investigation might.

2.4. Performance settings

These are security and performance settings:

• skipTemplateCheck: “Yes” or “No” (default “No”). When “No” (default), objects marked as template (i.e. they have the “is Template” property and it is checked) are automatically excluded from any results. When “Yes”, this additional verification is skipped and templates can therefore be part of the results (faster execution).
• skipObjectPermissionCheck: “Yes” or “No” (default “No”). When “No” (default), every queries will respect the user-level accesses / ACLs, so different users might see different results / numbers / lists of objects, depending on their permissions. When “Yes”, server-level accesses are used, so different users will see the same results, always (faster execution).
• serverScanMaxResults: Integer (default 500). The maximum number of M-Files objects fetched per widget query. You can set it to 0 for unlimited.
• drillThroughMaxResults: Integer (default 300). Maximum rows shown in drill-through modals and list tables. You can set it to 0 for unlimited. The pagination for the opened modal is set at 15 rows per page. Therefore, there can be up to 20 pages by default.

It will be covered in more details in Post 7, so I will not spend too much time on them here. The defaults are reasonable for most use-cases but you can change everything, of course.

2.5. Access control

Finally, the last parameter is about access control to the dashboard:

• assignedTo: An object with two optional arrays, users and groups. When the arrays are absent or empty, the dashboard is public. This means that ANY M-Files user will be able to select the dashboard from the dropdown. It does NOT mean that he will see something inside the widgets! Therefore, it gives access to the dashboard itself, but widget content still relies on the user’s ACLs by default (or server-level access if skipObjectPermissionCheck is set to “Yes”, c.f. above section). On the other hand, when at least one of the arrays is present, access is granted to any user who appears in the users array OR is a member of any group in the groups array.

In this example, the dashboard will be accessible by the user whose Login Account is Morgan.Patou OR any users part of the Finance Team OR Management groups:

"assignedTo": {
  "users": ["Morgan.Patou"],
  "groups": ["Finance Team", "Management"]
}

2.6. Widgets

• widgets (required): An array of widget objects. The order in this array is the order they appear on the grid. The size of the widget (column span, row span) is part of each widget’s definition (i.e. inside the array).

3. The widget object

Each entry in the widgets array has the following shape:

{
  "id": "",
  "title": "My Widget",
  "description": "An example description for My Widget",
  "type": "kpiNumber",
  "gridColumnSpan": 3,
  "gridRowSpan": 1,
  "query": { ... },
  "display": { ... }
}

Here is a quick description of the different fields:

• id (required): Same description as for the dashboard
• title (required): Name of the widget shown at the top of the tile
• description: Optional one-line italic subtitle just below the title. Annotate what the widget measures, or flag a caveat
• type (required): One of kpiNumber, gauge, donut, bar, line, area, table (covered in posts 4a, 4b, 4c)
• gridColumnSpan: Integer from 1 to 12 (default 4). Represent the width of the widget on the dashboard
• gridRowSpan: Integer (default 1). Represent the height of the widget on the dashboard
• query (required): The query the widget will execute. This can be pretty complex, so it will be detailed in Post 5 (filters) and Post 6 (aggregations), later
• display: Type-specific display options, like color thresholds, unit, decimals, etc. It will be covered per widget type in posts 4x as well

4. The query object in one paragraph

As mentioned, the detailed walkthrough of queries is the topic of Post 5–6, but for completeness, here is the basic shape of a query:

"query": {
  "objectType": "Document",
  "class": "Contract or Agreement",
  "filters": [
    {
      "property": "Effective through",
      "operator": "greaterOrEqual",
      "value": "@today",
      "valueType": "dateToken"
    }
  ],
  "aggregation": {
    "type": "groupByProperty",
    "propertyName": "Agreement type",
    "includeEmptyResults": "No"
  }
}

objectType can be a string or an array of strings (multi-object-type query). class is optional but strongly recommended for performance and to check only objects that actually matter… For example, you don’t need to fetch all documents (irrespective of their class) if you only want to count the number of active contracts. filters is an array of 1-to-N filter combined by AND. Finally, aggregation specifies the shape of the result and the reduction applied. To know more about these, please wait for the next posts.

5. The 12-column grid

The layout is computed on a CSS grid with 12 columns. gridColumnSpan sets the width of a widget, while gridRowSpan sets its height in row units.

Therefore, most common column layouts include:

• 4 widgets per row: gridColumnSpan: 3 each. Typical for KPI tiles.
• 3 widgets per row: gridColumnSpan: 4 each. Medium tiles or narrow charts.
• 2 widgets per row: gridColumnSpan: 6 each. Charts and tables.
• 1 widget per row: gridColumnSpan: 12. Full-width bar chart or wide table.

These are just examples. Nothing prevents you to set 3 widgets on a row with gridColumnSpan: 5, gridColumnSpan: 4, gridColumnSpan: 3 respectively. The Visual Designer is great for that since you get an exact view of what it will look like directly while creating the dashboard. More on that on the Post 8.

The widgets simply fill the rows from left to right in the order they appear in the widgets array, wrapping to the next row when a row’s spans sum exceeds 12. So planning the layout is largely a matter of ordering the widgets and giving each one a sensible column span.

For row height, a small subtlety: gridRowSpan: 2 does not give you exactly twice the canvas height of gridRowSpan: 1. It actually gives you roughly three times the canvas height, because each row unit subtracts a fixed overhead (header, padding, borders) from the available space. The practical consequence is that chart widgets (bar, line, area, donut, gauge) should almost always use gridRowSpan: 2 or higher. A single-row chart has very little drawing space and ends up cramped.

KPI number tiles, on the other hand, look fine at gridRowSpan: 1 and that is the right default for them. As a rule of thumb: KPIs at 1, everything else at 2.

6. Where the definition is stored

Dashboard definitions are stored in the vault’s Named Value Storage (NVS). They are NOT stored as a specific object in the vault. I initially thought about creating them as standard vault objects but in the end decided the NVS would probably make it easier for deployments and usage in the long run. The trade-offs of that choice:

• Pros: no extra object type to provision when installing the module, no ACL setup, no admin training on a new object type, no per-customer deployment friction. Backups of the vault include the dashboards automatically because NVS is part of the vault.
• Cons: there is no per-definition version history of the kind you would get with vault objects. I mitigated this by offering Import and Export buttons in the Admin tab that produce .json files. What I would recommend is to manage those files in a Git repository, which gives a clean and conventional version history outside the vault, with diff support.

The Export / Import buttons are the topic of Post 7. The TL;DR is that I would recommend that you should develop your dashboards on a DEV. Then, export them all into your git. Finally, when ready, import them into the TEST/QA/PROD environments, either manually or via CI/CD pipelines.

7. Quick overview of a full dashboard JSON definition

Putting everything together, here is a slightly more complete (but still small) example. It has some of the dashboard-level fields modified from their default values to show-case actions and buttons, and two widgets:

{
  "schemaVersion": 1,
  "id": "",
  "name": "Contracts",
  "description": "Quick overview of contracts",
  "autoRefreshEnabled": "Yes",
  "autoRefreshIntervalSeconds": 60,
  "userCanToggleAutoRefresh": "Yes",
  "exportToPdfEnabled": "Yes",
  "exportToCsvEnabled": "Yes",
  "skipTemplateCheck": "No",
  "drillThroughEnabled": "Yes",
  "skipObjectPermissionCheck": "No",
  "serverScanMaxResults": 500,
  "drillThroughMaxResults": 300,
  "assignedTo": {
    "users": [],
    "groups": ["Legal Team"]
  },
  "widgets": [
    {
      "id": "",
      "title": "Active Contracts",
      "type": "kpiNumber",
      "gridColumnSpan": 3,
      "gridRowSpan": 2,
      "query": {
        "objectType": "Document",
        "class": "Contract or Agreement",
        "filters": [
          {
            "property": "Effective through",
            "operator": "greaterOrEqual",
            "value": "@today",
            "valueType": "dateToken"
          }
        ],
        "aggregation": { "type": "summary" }
      },
      "display": { "unit": "contracts" }
    },
    {
      "id": "",
      "title": "By Agreement Type",
      "type": "donut",
      "gridColumnSpan": 9,
      "gridRowSpan": 2,
      "query": {
        "objectType": "Document",
        "class": "Contract or Agreement",
        "aggregation": {
          "type": "groupByProperty",
          "propertyName": "Agreement type",
        }
      }
    }
  ]
}

This dashboard renders as a single KPI tile and a donut chart on the same row (3 + 9 = 12 columns), with auto-refresh every minute and access restricted to the Legal Team group. Nothing exotic, this is the kind of dashboard most customers should probably start with.

If you wonder what it would look like, you can check the 1st and 2nd posts, they include these same widgets (though arranged slightly differently).

8. What comes next

In the next three posts (4a, 4b, 4c) I will go through the seven widget types one family at a time:

• 4a – Scalar widgets: kpiNumber and gauge.
• 4b – Trend widgets: line and area.
• 4c – Distribution and tabular widgets: donut, bar, table.

After the widget tour, Post 5 covers the query side (object types, classes, filters, date tokens) and Post 6 covers aggregations and reducers. By the end of those, you will have everything needed to write a non-trivial dashboard from scratch – if that’s what you want to do… Or you can just use the Visual Designer and follow along.

In the meantime, I hope this anatomy post gives you a clean mental map. If something is unclear or if you spotted a field whose behavior I have not explained here, please reach out so I can update the post.

Want to know more about this Business Dashboard? Contact us and we will be happy to showcase it on M-Files.

L’article M-Files BD – Anatomy of a dashboard definition est apparu en premier sur dbi Blog.

If you have followed my posts for some time, you know I prefer to walk you through a feature (or an issue) exactly as you would discover it. So, let’s do the same here.

1. Where to find the dashboard pane

The Business Dashboard adds a third tab to the right-hand pane of M-Files, next to the standard Metadata and Preview tabs. It is simply labelled Dashboard. Both M-Files Web (in a browser) and M-Files Desktop (the Windows client) show it – same panel, same behavior, with one platform-specific detail I will flag along the way.

As a reminder, this is what it looks like and how to access it:

If you do not see the Dashboard tab, two things are possible: either the module is not installed in your vault, or it is installed but your vault is configured to use the old UI. In both cases, the next step is to ask your administrator.

A small note on the pane width: the right pane is resizable by dragging its left edge. The dashboard AND the widgets inside respond to that resize. Therefore, on very narrow widths, widgets like donuts will have their legends move from the side to the bottom, to give more space to the charts. Don’t hesitate to play with the resize, it can be a good stress-reliever ;).

2. Selecting and switching between dashboards

At the top of the pane, you have a “Dashboard:” dropdown. It lists every dashboard your administrator has decided you can see, in the order the administrator chose. There might be more of them, but in this case, you don’t have permissions to see them. Click the dropdown, pick a dashboard, the panel updates immediately.

The last dashboard you selected is remembered for the next time you open the pane, so if you mostly use one dashboard (e.g. the Contracts one), you do not need to re-select it every morning. Even better than that, you can set multiple favorites and in this case they appear at the top of the list. More on that “last seen” vs “favorite” vs “link” below, in following sections.

Under the dropdown, if your administrator added a description to the dashboard, you will see a thin italic strip that contains it. It is clamped to two lines maximum. If the description is longer, hover the strip to see the full text in a tooltip. In addition to that, when the dashboard dropdown is opened, you will also be able to see the description of the dashboard you hover over, which will have a darker background.

In this screenshot, you can see the selected dashboard is about Contracts and its description is Quick view of contracts: active, …, while the description of the Invoices Overview dashboard is Purchase and Sales Invoice breakdown by year, workflow state, and customer.. Therefore, before loading it, you can get a quick idea on what exactly it will contain:

3. The widget grid

Each dashboard is a grid of widgets. As said, the grid is responsive and it contains 12 columns, so each widget can use from 1/12th and up to 100% of the width. Your administrator decides which widgets appear, in what order, at what size.

As of now, there are seven widget types supported:

Each widget has a title at the top, sometimes a short italic subtitle (the widget description, when your administrator added one), and three small elements in the top-right corner of the widget header that I will detail in the next sections.

4. Refreshing the data

Data on the dashboard is fetched live from M-Files. There are three ways the dashboard can be refreshed:

• Auto-refresh. If your administrator enabled auto-refresh, the panel re-queries all widgets at a configured interval (e.g. every five minutes). There is a small clock icon on the top-right corner of the Business Dashboard, which represent the Auto-refresh feature. When it’s off, the icon is grey, while it becomes green upon activation. Depending on configuration, you might be able (or not) to toggle the Auto-refresh.
• Global manual refresh. A small ↻ button in the top bar refreshes every widget at once. To avoid accidental hammering, the button enters a 15 second cooldown after a click. The per-widget refresh buttons are also locked during this cooldown.
• Per-widget refresh. Each widget has its own ↻ button in its top-right corner. Click it to refresh that widget alone. A 15 second cooldown applies to the clicked widget only.

Each widget header also shows a faint “Xs” or “Xm” or “Xh” text indicating when the data was last successfully loaded (in seconds, minutes or hours). Hover it to see the exact timestamp in a tooltip: “Last refreshed: hh:mm:ss“. This is useful to spot, at a glance, if all widgets were successfully refreshed or if there is one that is fresher than another (typically because you refreshed it manually).

5. Drill-through: exploring the objects behind the numbers

This is one of the features that makes the difference between an “interesting dashboard” and an “actually useful solution”. If your administrator enabled drill-through on the dashboard, all widgets automatically become clickable, and clicking them opens a detail modal listing the underlying M-Files objects.

What is clickable:

The modal that opens shows a table with one column for the object name (as a clickable link – c.f. navigation section below), plus any additional columns your administrator configured. Columns are sortable: click a column header to sort ascending, click again for descending. Sorting applies across all fetched rows, not just the visible page. So if you sort an “Amount” column descending, you see the top 15 (that’s the default page size, but it is configurable, c.f. below with an example of 25) of all the rows that were retrieved, not just the page you happened to be on.

Note: Sometimes the bar shows a small warning like "(⚠ 500 object(s) fetched)". This tells you the server retrieved up to its scan cap and there may be more objects in the vault that did not make it into the modal. Hover the icon for an explanation. If you regularly hit that cap on a widget that should show everything, your administrator can raise (or disable) the cap on the dashboard configuration.

Why drill-through can potentially show more objects than the widget counts

This deserves its own paragraph because it might be a bit counter-intuitive at first. The widget aggregation runs inside a capped scan (set by your administrator), while drill-through runs a focused search with the slice or row category as an additional filter. If the focused search can fit all matching objects under its own cap, you may see more objects in the modal than the widget counted.

The Partial results badge on the widget header (when present) is the warning that the widget aggregate may be incomplete. There are basically two different limits. A first global limit, that ensures we do not request too much from the server and a second one linked to the drill-through that applies on filtered results.

Example: A dashboard has been configured by your admin with 10’000 for the first limit and 5’000 for the second. Let’s take a Documents by Class donut widget (i.e. you want to see ALL documents – without any filters). If your vault has more than 10’000 objects of type Documents, then the widget would display 10’000 with a Partial results badge. In these first then thousand results, there might have been 150 Contract or Agreement (Class) shown in the donut. If you click on the donut slice for Contract or Agreement, the associated modal will open and it will show at least 150 and up to 5’000 results. In the end, if the initial search is “too wide”, you might hit a limit. But the drill-through will include another filter (here “Class=Contract or Agreement”), which only return these specific objects.

Again, this is for performance reasons and as a kind of server-protection. If you have a real need, these limits can be increased or disabled completely by the admin – it is simply like that by default.

6. Navigating to an object

In drill-through modals and in list-type table widgets, object names are blue underlined links. Clicking a link opens that object on the left-side of M-Files.

A small detail that is sometimes useful: the drill-through modal stays open after you click a link, so you can navigate to several objects one after the other without losing your place in the list. Close the modal manually when you are done (using the × button, the Escape key, or clicking outside the modal).

7. Exporting to PDF

If your administrator enabled PDF export, a ⎙ PDF button appears in the top bar of the dashboard. Clicking it generates a snapshot of the current dashboard state (charts as images, KPI numbers, tables) and opens a print dialog automatically (both on Web and Desktop). From there:

• Select “Save as PDF” (or “Microsoft Print to PDF”) as the printer and click Save.
• Or pick a physical printer to print a hard copy.

The top bar, the refresh buttons and any open modals are excluded from the snapshot, so the PDF stays clean.

Note 1: if your client blocks the automatic print dialog (a rare but possible restriction), an HTML file is downloaded instead. You can open that file in any browser and press Ctrl+P to print it in the exact same way.
Note 2: the PDF export will respect exactly what M-Files is currently showing. This allows you to export the dashboard with a specific configuration. For example a table sorted in a different way that the default one, or some legends unselected from a donut, so that it ignores these details and re-render the donut with the remaining categories or time periods, etc. Whatever M-Files is showing will be what is present in the PDF export.

A PDF export of a dashboard will look like that:

8. Exporting to CSV

Similarly to the PDF export, your administrator can also enable CSV export. When it is on, a ⊞ CSV button appears in the header of every table, bar, donut, line, and area widget, as well as in the header of the drill-through modal for all widgets.

Clicking ⊞ CSV downloads a .csv file immediately. There is no extra server call; the export uses the data already in memory, so it is fast.

The file starts with a small metadata block describing what the data represents / how it was fetched:

Widget Name,Active Contracts
Object Type,Document
Object Class,Contract or Agreement
Filter #1,Effective through greaterOrEqual @today
Aggregation Details,summary | count
Export Date,2026-06-04 19:30:08

There might be two additional lines if the export is done on a specific group (a part of the initial results (e.g. after opening a donut’s slice modal details)) and if the widget is configured with multi-series. One line will describe which group is exported (category or time period) and another will describe the second dimension (the series).

The above metadata section is followed by a blank separator row (empty line), then the actual data rows (column headers and associated values). All rows currently held in the browser are exported, not just the page you are looking at. For example, if the table shows page 2 only (objects 16-30) but 120 results were fetched, then all 120 rows will be in the CSV.

The CSV file exported can then be opened in your preferred editor (Microsoft Excel, Euro-Office, LibreOffice, etc…). In the below image, I simply added the headers in Bold, but otherwise it’s the default outcome.

Note: similarly to the PDF export, the CSV will also respect table sorting, so that the rows exported will be in the exact same order as the one that you see on your screen.

9. Multiple favorite dashboards

If you use some dashboards far more often than the others, you can pin them as your favorites. There is a small star button (☆) in the top bar:

• Select the dashboard you want to pin.
• Click the ☆ button. It turns gold (★).
• From now on, when you open the Dashboard pane, the first dashboard you set as favorite will load first (instead of the last you viewed), and you can access your favorites at the top of the dashboard dropdown.

To unpin, click the ★ again. The favorites are stored under your account, so it follows you across clients and devices. Do it once and you can then enjoy forever.

10. Sharing a dashboard link

Right next to the favorite button, a small link button () can be used to share a link to a specific dashboard with someone else. In both M-Files Web and M-Files Desktop, the clipboard will be updated to contain a link to the current dashboard. For that purpose, the administrator will have to set the public facing URL of M-Files in the M-Files Admin configuration.

If this public URL isn’t defined, then it will still work on M-Files Web, by automatically fetching the current URL and appending it with the reference to the current dashboard ID. However, on M-Files Desktop, the URL is actually a local one, which nobody else will be able to use and therefore, the fallback is to copy the dashboard Name instead.

11. Indicators worth knowing

A few small visual indicators are worth recognizing:

• Partial results (orange badge in the widget header). The server scan cap was reached; the widget may not reflect the full data. Section 5 above has the full explanation.
• Grey placeholder text inside a widget. The dashboard definition has a small mis-configuration. The administrator was normally warned about it when he designed the dashboard but he probably ignored it.
• Red error overlay that replaces a widget. The server returned an unexpected error. The dashboard definition has a configuration problem. The dashboard designer part (admin) doesn’t allow to Save/Publish dashboards with such errors, but someone might have bypassed the administrative tool and updated the database directly.
• Spinning overlay. The widget is loading. If it stays in that state for a long time, the vault may be under load. Use the per-widget refresh button to retry once the spinner disappears. I haven’t seen the spinner stays more than 2 seconds myself, but I guess it could happen.
• Numbers higher than what you see in your views. Dashboard widgets can use either user-level permissions (default) or server-level permissions, depending on the configuration done by the administrator. Some use-cases might require to give access to all M-Files users to some KPIs for example. In this case, a dashboard could use server-level permissions, so that the KPIs are accurate and the same for everybody, even people with no access to the underlying objects. The navigation (links) to the objects will always respect your actual user-level permissions, obviously. So the only thing that the dashboard can give you access to, if configured in that way by the administrator, is KPIs or some charts (possibly even without the drill-through – so you don’t have any details about the objects themselves).

12. What comes next

What I believe is genuinely useful about this module, is that it removes the small friction of “I just want to know quickly”. Opening a Power BI report takes a context switch; opening a saved view, scrolling and counting takes time. The Business Dashboard sits one click away in the M-Files window the user is already in, and it shows the answer he is looking for with nice visuals.

In the next post of this series, I will move to the other side of the panel: how an administrator configures a dashboard. I will start with the anatomy of a dashboard definition – the JSON structure that drives everything you just saw.

Want to know more about this Business Dashboard? Contact us and we will be happy to showcase it on M-Files.

L’article M-Files BD – End-user experience est apparu en premier sur dbi Blog.

The starting point was a real observation: the views of M-Files are powerful, the metadata model is flexible, the workflows are solid, but getting an at-a-glance picture of the business is still a clicking exercise. You open a view, you count, you open another view, you count again, you switch to the search, you start building an Excel with what you found… However, you might still not have the chart you wanted to present in the management meeting that starts in ten minutes.

This blog post introduces what I called the Business Dashboard module, a custom M-Files extension designed and built to fill that gap. This is the first post of a series that will walk through the module. From the end-user experience, to the authoring side, and finally to a complete worked example. I will use the M-Files Sample Vault for this series since it contains test data. You can quickly and easily deploy that vault via the M-Files installer.

1. The problem to solve

As you might know, M-Files ships with a few visualization features (views, search facets, the right-hand Metadata and Preview panes). With these, you can answer one of the following questions, but never all at once and never at a single glance:

• How many contracts are currently active in the vault?
• How many of them expire in the next 30 days?
• What is the distribution of our contracts by agreement type?
• What is the total amount of invoices waiting to be approved, broken down by customer?
• How many documents was each employee responsible for last quarter?

These are not exotic questions. They are the kind of things you might face every week. And the honest answer, today, is “I will get back to you later”. Sometimes there is a Power BI dashboard plugged into the vault SQL backend that answers some of them, but that is a second tool, a second login, often a second team to involve, and usually a permission/access story that does not match the per-user M-Files context.

I wanted something simpler. Something that lives inside M-Files, that integrates with the M-Files access model, that an administrator can configure without writing any code, and that the end user can open with one click from within M-Files.

2. What the Business Dashboard module is

The Business Dashboard is an additional panel that appears on the right-hand side of M-Files (alongside Metadata and Preview). It works in both M-Files Web and Desktop (latest UI). End users pick a dashboard to render, which contains widgets (tiles) that display live business data from the vault using KPIs, donut, bar, line, area, tables or gauges. Data is fetched live from M-Files and it can refresh itself. It provides multiple other features such as export to PDF or CSV, favorites, links, even object navigation, etc… From a security point of view, the access control will be in Post 7.

For administrators, dashboards are defined as JSON documents edited inside a dedicated tab in M-Files Admin. The editor offers both a JSON editor and a Visual Designer that lets you build dashboards without any knowledge of what JSON is. Definitions are stored in the vault, so a backup includes them automatically and there is no extra database to provision or manage.

Two design choices are worth pulling out here, because they shape everything else in the series:

• The engine is fully generic. There is no hardcoded business concept anywhere in the code. The same module works for contracts, invoices, customers, employees, projects, or whatever objects is contained within your vault. The JSON tells the engine how to query (which object type, which class, which property to group by, which filter to apply), not what values to expect.
• The wire format is frozen. Once the dashboard JSON is saved, the calls between the UI and the server speak a fixed shape. This means that when/if I ship a new widget type or a new aggregation, existing dashboards will keep working with no migration.

This is what the Business Dashboard looks like, from end-user point of view (click to enlarge the image):

3. Concrete use cases

Rather than list features, let me describe four concrete scenarios where the Business Dashboard could shine:

• Contracts overview. A KPI tile showing the number of active contracts, another showing those expiring in the next 30 days, a donut chart by agreement type, a bar chart showing expiries per month for the next year (e.g. until end of year or next 365 days), and a list of contracts to review this week. One panel, no clicking, refreshed automatically.
• Purchase invoices. Total amount waiting for approval, oldest invoice still pending, distribution by customer/countries/regions, a gauge of overdue invoices against a target of zero.
• Employees and responsibilities. A list of employees by department, with the count of documents worked on by each one in the past week. Possibly the list of people in holidays with their substitute. Useful for capacity planning and for the “who is on vacation, who covers what” conversation.
• Customer activity. Documents by customer in the last quarter, broken down by document class. Quickly spot the customers who went quiet and the ones who suddenly became very active.

None of these are hardcoded in the module. They are examples of what an administrator can configure, once, using the Visual Designer or the JSON editor. The same engine produces all of them and any number of variations.

Note: Whatever the widget used, with at most one more click, you can get the details of which objects correspond to what you are looking for. For example, if you have a KPI for the number of active contracts, if it shows 25, then simply clicking on that 25 will open a drill-through with the list of all 25 objects in that specific situation, with optional additional details. See the follow-up posts for more details on that (and all other features).

4. Where it runs

The module contains two parts:

• BusinessDashboard – the server-side, which contains the query engine, the validator, the persistence layer, etc.
• BusinessDashboard.UIX – the client-side, which contains all the display part for the end-users.

Both are installed, independently, in the M-Files Admin, via the standard application installation process. In regards to compatibility, it should technically supports all recent versions of M-Files that uses the new UI. I personally tested it extensively on M-Files 26.3 / 26.4 / 26.5.

No external service is contacted; everything runs inside the vault. This makes the module a good fit for both on-premises and cloud deployments (though for cloud, the module would need to first be validated by M-Files), or for any deployment where adding a second tool (Power BI, Grafana) is not desirable (too complex to setup, too much for the actual need, or simply for security reasons).

5. What this module is not

I think it is fair, before closing this introduction, to flag what the Business Dashboard module is not trying to do.

• It is not a BI tool. No SQL access, no data warehouse, no cross-vault joins. The engine only queries the M-Files vault it is deployed on and that’s it. If you need to combine data from a vault and an ERP, a dedicated BI stack might still be the right answer. UNLESS you are already merging the ERP data in M-Files (external repository or database connector). In that case, the Business Dashboard would be able to query it as well.
• It is not (really) a reporting engine. No scheduled report, no email delivery. However, you can export a dashboard as PDF and you can export a widget (or its drill-through) to CSV (Excel-compatible).
• It is not (really) designed for very large aggregations. The engine fetches up to a configurable amount of objects per widget (500 by default – can be increased, decreased or disabled completely…). Then aggregates it in memory, which is fine for any reasonable business question. Though it is not fine for things such as “list all 50 million objects that were created in the last 10 years”… If the limit is hit, the user knows about it with the help of a special badge.
• It is not a replacement for M-Files views (or is it…?). Depending on use-cases, views can still be a better starting point. The Business Dashboard sits next to them, not in front of them.

If your need fits inside those boundaries, the module might make your life easier, irrespective of whether you are a decision maker, a power user, a simple user or an administrator. If it does not, please get in touch and I will be happy to discuss what would!

6. What comes next in the series

This series is going to cover, in order:

• Post 2 – The end-user experience: opening the panel, switching dashboards, drill-through, exports, favorites, sharing.
• Post 3 – The anatomy of a dashboard definition: the JSON structure that drives everything.
• Posts 4a, 4b, 4c – The widget catalog, split by type family: scalar widgets (kpiNumber, gauge), trend widgets (line, area), and distribution / tabular widgets (donut, bar, table).
• Post 5 – Writing queries: objectType, class, filters, date tokens.
• Post 6 – Aggregations and reducers.
• Post 7 – The Admin tab: actions, Visual Designer / JSON editor, validation, import / export, access control.
• Post 8 – Building a dashboard with the Visual Designer.

If you have a specific question or a use case you would like to see covered in the series, don’t hesitate to reach out, and I might be able to add it to my to-do list.

In the meantime, the next post will be a tour of what an end user sees the first time they click on the new Dashboard tab. See you there.

L’article M-Files – Introducing the Business Dashboard module est apparu en premier sur dbi Blog.