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.

As consultants, we constantly face new challenges, many of which extend beyond purely technical matters, while adapting to diverse contexts and audiences.

That’s what makes this profession so exciting!

At dbi services, knowledge sharing is deeply embedded in our culture.

Over the past three months, I’ve had the opportunity to share my experience working on ECM projects for years.

This post concludes the series by highlighting the key insights that have shaped my approach to these projects.

Stop thinking “System first”

In my previous roles, I was more of a product specialist than a solutions specialist. My job was to adapt clients’ needs to the software framework.

Now, working for a company that isn’t a “pure player” enables me to select the optimal solution from the beginning rather than having to adapt, of course I love M-Files, but alfresco is another solution we like!

For me, the right approach is certainly not:
“What can this ECM do?”

Rather, it is:
“What business problems do we need to solve first, and for whom?”

ECM initiatives often fail when they attempt to tackle everything at once rather than focusing on what truly matters. In practice, users don’t adopt tools just because they exist, they embrace solutions that directly address their daily pain points. That’s why achieving early, tangible success is critical. It builds credibility and helps secure continued investment.

Rather than implementing broad, I would focus on three to five high-impact use cases, such as invoice processing, contract lifecycle management, and quality documentation.

These cases should deliver measurable results within weeks rather than quarters. Each use case should be treated as its own product, with a clear value proposition and user-centric design, rather than as just another feature within a larger system.

Put adoption at the center

I used to think: “If the solution is good, people will use it.”

That’s wrong.

Adoption requires preparation. It doesn’t just happen on its own.

The hard truth is that the best ECM solution with no adoption equals failure.

What I’d do differently:

• Identify the key users early on. They will help you get the solution adopted
• Design in collaboration with actual users, not with their representatives.
• Invest time and resources in on-boarding with in-app guidance, simple training paths, and internal champions.

Remember, if users need a manual to use the solution, you’ve already lost them.

Simplify the information model

One of the biggest mistakes I’ve seen (and made) is overengineering metadata and taxonomy.

We aimed for a perfect structure. We got complexity.

The reality is that users don’t care about your taxonomy. It adds complexity, makes classification difficult, slows down their work, and ultimately reduces user adoption.

Here’s what I’m doing now:

• I’m trying to limit the number of fields to seven or fewer.
• I take full advantage of automation features, such as default values, smart classification, and recognition.
• I use an iterative approach if it results in tangible improvements.

A good structure that is used consistently is better than a perfect one that nobody follows.

Design for automation

Projects often treat automation as a second phase. For me, that’s a mistake.

Today, without automation, ECM is just a digital archive.

Here are some things to do from day one:

• It is essential to pinpoint tasks that are repetitive in nature and convert them into workflows. Examples of such tasks include approvals, classification, team collaborations, and more. This conversion process must be incorporated into the initial release.
• Use AI carefully and for meaningful topics. AI is trendy and can benefit us if we use it to accelerate work in areas such as classification, translation, and summarization, not just because it’s hype.

The goal is to eliminate unnecessary work and allow users to focus on what is important.

Measure the right things

Keep in mind that success metrics are not the number of documents migrated, users trained, or system uptime.

True success is measured by the positive impact the solution brings, such as reduced processing time, increased adoption, improved compliance, and saved time.

Measure the real impact to prove added value.

Treat ECM as a product, not a project

This is a common mistake that I still often see during ECM implementation, and it needs to change.
An ECM is not a static project consisting of analysis and implementation, and then it’s finished.

We must adopt an agile approach of building, learning, improving, and repeating.

As soon as users start using the solution, we must maintain a backlog of improvements, perform regular releases, and continuously gather user feedback.

An ECM project is never truly finished because it must evolve with business needs. Otherwise, businesses will adapt their work to the tool and slowly abandon it.

Don’t forget the governance

Although governance is essential, it can also become an obstacle.

I’ve seen governance frameworks delay projects by several months because they lack flexibility.

Nothing is perfect, so while you should meet compliance requirements, keep things simple.

Clearly define responsibilities from the start:

• Who is responsible for metadata?
• Who approves changes?

Ensure that governance remains light and practical.

Strike the right balance between control and ease of use.

Think about who you’re doing it for.

Although IT leads this type of project, users are often not part of the team.

Therefore, establishing strong collaboration between IT and business users is crucial.

Involve users in the decision-making process.

Hold them accountable for adoption, this is a company-wide project, and its success depends on them.

The platform is just a tool

To sum up my years of experience in ECM.

While it’s initially reassuring to master a product and understand its inner workings, ultimately, clients don’t care about that.

They have various problems and want a solution and very often, the specific product doesn’t matter.

They count on us to recommend the most suitable solution because they are busy running their business and don’t have time to compare products on the market.

ECM success isn’t just about managing documents; it’s about enabling better work.

• Help users work more efficiently.
• Provide business value.
• Improve the user experience over time.

If you’re about to start a project, ask yourself:

• Are we solving real problems?
• Are users involved from day one?
• Are we delivering value early on?

If not, now is the perfect time to ask us for help!

L’article After years of ECM projects, here’s how I do things differently nowadays 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.

When everything was delivered on time and within the budget. Yep it’s not fiction, it happens really

Every KPI is green!

At the last steering committee meeting, congratulations were in order. A slide presentation highlighted the project’s key milestones, its features, and its smooth rollout. Everyone agreed that it was an exemplary project.

However, month after month, interest gradually declined and fewer employees used it.

There was no official postmortem or formal acknowledgment. It just gradually faded into irrelevance.

This is the story of a project that seemed successful but actually wasn’t.

Why does it look successful?

At first glance, everything seems perfect:

• Deadlines are respected.
• Budget is controlled.
• Scope is delivered.
• Stakeholders are informed.

All of the classic project management success criteria were met.

However, those metrics measured output, not outcome.

No one asked the simple question:

Did the project actually solve the intended problem?

Behind the illusion

Under the surface, cracks were real, if you knew where to look.

Here are some key points:

Users

The training sessions were completed. The documentation was published.

But what about adoption? It remains minimal.

Employees continued to use spreadsheets, emails, and old tools. Though technically superior, the new system felt like a constraint rather than support.

It wasn’t part of their workflow. It was an extra step.

Requirements

The team implemented everything according to the original specifications.

However, no one ever questioned those specifications.

Also, the team wrote them too early, based on assumptions and disconnected them from actual user behavior.

As a result, the project delivered exactly what stakeholders requested,but not what users needed.

Success was narrowly defined

The project team optimized for:

• Delivery speed
• Cost control
• Scope completion

What they didn’t optimize for:

• User adoption
• Business impact
• Long-term value

When success is defined narrowly, failure has space to hide.

Feedback ignored

During the pilot phase, users raised concerns:

• “This doesn’t fit our daily work.”
• “This adds complexity.”
• “We don’t see the benefit.”

Rather than viewing these signals as valuable insight, they were labeled as resistance to change.

It’s easier to push forward than to pause and rethink.

Premature victory

Once the project was delivered, attention shifted elsewhere.

There was no plan for:

• Adoption tracking
• Continuous improvement
• Measuring real outcomes

The project ended when it should have evolved.

The cost behind that

Because everything appeared successful, the failure went unnoticed.

But the cost was real:

• Lost investment
• Frustrated users
• Erosion of trust in future initiatives
• Reinforcement of shadow IT (spreadsheets, workarounds, etc.)

Even worse, the organization learned the wrong lesson:

“We know how to deliver successful projects.”

Lessons learned

As I’ve written several times in previous blog posts, ECM failures are rarely due to the solution itself.

Rather, they are due to how it was implemented and the lack of improvements after it went live, an ECM is a living system.

Here are some point that need to be appreanded differently:

Redefine success

Move beyond the classic triangle of time, cost, and scope.

Focus on what brings business value:

• adoption
• user satisfaction
• simplification and consolidation of processes

If people don’t use it, it’s not successful.

Be realistic

Specifications should not be set in stone.
They should evolve based on the following:

• user feedback
• iterations
• real-world testing

Projects fail when assumptions take precedence over observation.

Think critically

A fully green status report can be misleading.
Ask deeper questions:

Are users engaged?
Are behaviors changing?
Is there a measurable impact?

If the answers are unclear, the project isn’t finished.

Go-Live is the beginning

Delivery is not the finish line, but rather the starting point.
Real success happens after adoption, iteration, and proven value.

Listen to resistance

Resistance is often misinterpreted.

It is rarely a matter of resistance to change, but rather a matter of recognizing that every complaint reveals a discrepancy and provides a clue for improvement.

Finally

The most dangerous projects are not the ones that fail visibly. When a project fails, we know why.

The real danger lies in projects that succeed…on paper.

Everything looks good because we aren’t considering what makes sense.

It’s important to keep in mind who we’re doing those kinds of projects for: the users, and why: to help them with their daily work.

Everything else is nonsense.

If you’re interested in making your ECM project with M-Files a true success, feel free to contact us at dbi services, we’d be happy to help.

L’article A project that looked successful. But… 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.

The benefit is real; otherwise, I would have moved on to something more meaningful. However, this promise isn’t so straightforward.

Most ECM ROI models are overly optimistic and lack objectivity.
It’s not always intentional, though. But they are systematically so. They persistently misrepresent the facts. Often, they are politically motivated. After all, this is business.

As a vendor-free ECM consultant, I will try to take an objective look at it.

The myth of measurable value

ECM vendors and internal champions love spreadsheets.
They’re full of neat formulas like:

• Save 5 minutes per document
• Process 20,000 documents per year
• Average employee cost: 75 CHF/hour

Result: 125000 CHF annual saving.

Looks solid, right?

But it’s not!

The problem

This model assumes that time savings are perfectly converted into productive output, that organizational friction magically disappears, and that users actually change their behavior.

In reality, things are more nuanced. Saved time becomes micro-idle time rather than reinvested capacity. Users continue to work around the system, and the complexity simply shifts elsewhere instead of disappearing.

If your ECM project “saves time,” ask yourself: where exactly does that time go?

If you cannot demonstrate a real reduction in costs or an increased throughput, then your ROI is theoretical.

Fake precision

ROI models often disguise assumptions as facts.

Typical inputs:

• “Average handling time before ECM”: estimated
• “Handling time after ECM”: projected
• “Error rate reduction”: assumed
• “Adoption rate”: overestimated

These are not actual measurements, but rather assumptions (sometimes bordering on wishful thinking) that are expressed as numbers.

When you multiply uncertain assumptions together, you don’t get accuracy, you get amplified uncertainty.

Yet the final number is presented with:

• Two decimal places
• A confident tone
• A fancy PowerPoint slide

This creates the illusion of rigor.
However, it’s still just guesswork in a better format.

The political nature of ROI

That’s where things get complicated.

The return on investment for ECM projects often doesn’t reflect reality.

The main goal is to convince decision-makers.

Who needs ROI?

• Project sponsors → need funding
• Vendors → need deals
• Consultants → need positive vibes (Yep, I don’t want to work with customers who don’t recognize the value I bring.)
• Managers → need justification

So what? the ROI model becomes a political artifact:

• Inflated enough to pass governance
• Flexible enough to survive scrutiny
• Vague enough to avoid accountability

No one says:

“We don’t really know the value, but we think it’s worth doing.”

Instead, they say:

“This project will deliver €2.4M in savings over 3 years.”

Everyone knows it’s lax. But (very) few people are willing to question it.

Misleading indicators (that seem convincing)

Let’s look at the usual suspects.

Time saved

Most overused metric in ECM.

• Highly variable
• Rarely measurable at scale
• Almost never translated into realized financial gain

The truth is that saving time and saving money are not the same thing.

User satisfaction

It often increases temporarily, mainly due to the initial gains associated with novelty. Then, it declines as complexity sets in.

It is difficult to establish a link to business results.

Satisfied users alone do not justify platforms that cost millions!

Documents Processed Faster

It sounds powerful, but is it really challenging? Does faster generation actually generate more revenue? Is there a bottleneck at this stage?

Just because you do things faster doesn’t mean you’re creating value!

The real economic impact

The question to ask is: Which economic variable is actually changing?

Real ROI should come from:

• Avoid hiring and even reduce headcount.
• Increased transaction volume
• Shorter revenue cycles
• Lower regulatory penalties (measured, not hypothetical)
• Reduced external costs (printing, storage, outsourcing)

If your ECM project doesn’t impact at least one of these directly, your ROI is likely cosmetic.

Why the “lie” persists

If the flaws are so obvious, why does this narrative persist?

Because it delivers, at least in the ways that matter internally. It secures budget approval, aligns stakeholders around a common narrative, and provides a simple, reassuring story.

To be fair, many ECM projects do create value, just not in a way that can be easily captured in a spreadsheet.
Thus, the industry quietly sustains a shared illusion. It’s a cycle where belief matters more than proof and ROI becomes a tool for getting things done rather than a measure of value.

What to do instead?

Don’t get me wrong, ECM is one of the most important business applications.

The problem lies in how the project is presented, which seems dishonest to me.

As soon as human beings are involved, we can no longer rely solely on mathematical formulas. Consequently, ROI calculations are theoretical and idealized.

Nevertheless, the benefits are very real. Rather than claiming users will save five minutes per document, it’s better to state that the approval process has sped up by 20 or 30 percent and that the follow-up system is now automatic and systematic rather than dependent on an employee’s availability for that task.

Just because not everything can be monetized doesn’t mean we aren’t delivering operational value. ECM goals are to improve and simplify daily work or add strategic features.

Instead of hiding your assumptions, list them explicitly and present various possible scenarios based on confidence levels.

To avoid surprises after implementation, we must ask the tough questions.

• What will happen if the adoption rate isn’t as high as expected?
• Will this project reduce costs, or will they simply be shifted elsewhere?
• Who is responsible for delivering this value?

Ultimately, an ECM project is never just a financial equation. At dbi services, we refuse to reduce a project’s value to an artificial or approximate ROI. We focus on the real values that ECM delivers on a daily basis: human, operational, and strategic. These values are realized long before the attractive but often misleading numbers. Our goal is not to promise theoretical savings, but to tangibly transform the way teams work, collaborate, and make decisions.

L’article The ROI mirage in ECM projects 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.