CtrlPortals troubleshooting

Pages here are titled by symptom — what you see — rather than by cause.

Three things cause most of what looks like a fault in CtrlPortals: the client is still holding an older copy of the configuration, the licence is not answering for the user who is asking, or M-Files is answering correctly and the answer is unwelcome. Rule those out before reading a section.

Check these first

Four things account for most reports, and all four are quick to rule out:

Has the configuration been refreshed? A configuration change reaches the client only through Refresh Configuration, in the CtrlPortals entry of the client’s menu. A change that appears to have done nothing has usually not been refreshed.
Was the vault restarted after installation? A vault application does not start until the vault restarts, and the restart does not begin until the Applications dialog in M-Files Admin is closed. An installed-but-never-restarted application looks identical to a broken one.
Is the licence valid? Open Applications, select CtrlPortals, and select License. Expiry dates are only shown here, and nothing warns you in advance.
Is the user seeing a permissions result rather than a bug? A portal reads M-Files as the signed-in user. If an object is missing from a list view, check whether that user can see it in M-Files itself before investigating the configuration.

Nothing from CtrlPortals appears at all

No portal opens on any object, and the menu holds a CtrlPortals group with nothing in it but Refresh Configuration.

When the application will not answer for a user it answers with an empty configuration rather than with an error: no portals, no dashboards, no dashboard groups. Two conditions produce exactly that, and neither says anything in the client.

The licence is missing, invalid or expired. M-Files Admin reports it against the application as License invalid or expired, your Portals installation has been deactivated.

The licence names user groups, and one of them has outgrown its allowance. A licence can be issued against named M-Files user groups, each with a maximum number of members. A user is served the configuration only while they belong to one of those groups and that group is still within its member count. Add one person too many and every member of that group loses their portals at once. Compare each named group’s membership against the licensed number before looking anywhere else.

A toast says the configuration could not be loaded

The message is Could not load the CtrlPortals configuration, and it names the underlying error.

The client asks the vault application for its configuration when the frame starts, and retries a few times before giving up. A vault that is still starting — after a restart, or after the server was rebooted — has not registered the application’s endpoints yet, and the retries run out first.

Use Refresh Configuration once the vault is ready. The command is created even when the startup load failed, precisely so there is a way back without restarting the client.

No portal opens when a user selects an object

A portal is matched by the object’s class and by nothing else, so check the portal’s Classes list first — an object type is not enough, and a portal with no classes never opens. Which portal opens has the three cases and what each looks like.

One thing that is not this: with Open Default off, the portal tab is still there. The metadata card stays selected until the user chooses the portal, which reads as the portal missing.

A list view has the wrong columns, or only one

The table’s columns are the M-Files view’s columns, read from the view’s common display settings. A user’s own column choices are personal display settings, which the portal never sees — which is why a view that looks right in the client can arrive as a single size column.

In the M-Files client, open the view, right-click the column header and choose the columns worth seeing, then right-click again and choose Save as common display settings. That option needs the manage common views right, or full control of the vault.

Changing the columns is a change to the view rather than to the component, so no configuration refresh is involved.

A list view lists group names instead of objects

A view with grouping levels returns its groups at the top level rather than its objects, and the table shows what the view returned. Where the table has a type column, those rows give themselves away by reading Common View or Personal View in it.

Group by type, in the component’s List view section, is what drills past the grouping. It defaults to Current Object, which is right for a portal over a view grouped by the object being shown. The other cases:

On a dashboard. There is no current object to drill by, so a grouped view always returns its groups. Point a dashboard’s list at a view with no grouping levels.
Grouped by something other than the current object. Set Group by type to Lookup Property and name the lookup on the current object in Group view by property.
The object has no value in that property. There is nothing to drill by, so the groups come back again. That case is better hidden with a portal rule than fixed.

To group the rows the table already has, use Group values by type and Group values by property instead. Those draw group headers inside the table and have nothing to do with the view’s own grouping levels.

Rows are missing from a list

Start with permissions. A list view respects M-Files permissions, so a user seeing fewer rows than you do is correct rather than faulty. Compare against the same view in the M-Files client, signed in as that user.

A Multi view stops at 100,000 rows and says so under the table: Showing the first N rows; the result was truncated. Narrow the data source rather than raising anything.

A plot is empty

Run the series’ conditions as a search in the M-Files client before touching any chart setting. A plot with nothing on it nearly always has a series returning nothing.

If the series is right and the chart is still empty, the plot has not picked up the change. Plots read through a cache of their own, so a configuration change needs a refresh as well.

A plot shows figures that are out of date

Query results are cached. Cache lifetime (minutes) sits on the query configuration and again on each M-Files trace, and defaults to 30 minutes; 0 disables the cache and makes every viewer pay for a full query.

The refresh button in the chart toolbar, in the top corner of the plot, clears the cache and reloads the data. Use it to tell a stale cache from a wrong query: if refreshing fixes the figures it was the cache, and if it does not the query is wrong.

Five minutes is the practical floor. Below that the cache stops paying for itself and the vault carries the load instead.

A plot fails on a property with several values

The message is one of:

There are too many multi-selections, width 20 exceeds max of 18.
There are too many combinations of multi-selection values, combinations 900000 exceeds max of 524288.

Grouping by a multi-select property means every combination of its values has to be resolved, and the query engine refuses the ones it cannot hold. Maximum Multi-Select Width (18) and Maximum Multi-Select Depth (524288), under Query engine configuration, are the two ceilings.

Narrow the series before raising either. Both limits exist because the combinations are held in memory on the server, and a chart needing more than eighteen multi-select layers is usually answering the wrong question.

In order of how often it is the answer:

Its groups do not reach the user. A dashboard group narrowed with Target user group is filtered out on the server for everyone outside it, and a dashboard whose every group has been filtered out goes with it. Nothing reaches the client, so there is nothing to find there.
Its group identifier matches no group. A dashboard’s Groups entry refers to a dashboard group by unique identifier. If that group has been renamed or removed, the reference matches nothing and the dashboard disappears for everyone. A dashboard in no group at all is fine — it falls back to the default group.
Visibility is set to Hidden. That keeps a dashboard out of the menu deliberately, for one reached through a view binding.

A newly added dashboard group is a separate problem: until the configuration is refreshed in M-Files Admin, the group is not offered in the list a dashboard can join. See Dashboards.

A component appears when a rule says it should not

A rule that cannot be evaluated is treated as true, so the failure mode of a broken rule is a component that is always shown.

The name is misspelled or belongs to another portal. The client raises a toast titled Error when evaluating rule: "…" whose text is Unknown Identifier 'x'. Please check the configuration and look for misspelled or missing portal rules. Rules are read from the portal that matched the object’s class, so a rule defined on a different portal is unknown here even though it exists in the configuration.

Two rules share a name. Names are matched without regard to case, and the last one in the list wins.

The rule’s conditions could not be evaluated. The application log records Could not evaluate portalRule <name> and the rule returns true.

Nothing in the application status reports a misspelled rule, so the toast is the first sign. See Portal rules.

A property placeholder shows as text in an HTML component

%PROPERTY_1162% appearing verbatim on the portal means property 1162 is not in Properties to Expand in HTML, in the component’s HTML section. Only the properties on that list are substituted; a placeholder for anything else is left exactly as written.

A placeholder that vanishes instead is the other case. The property is listed, the object has no value for it, and Fallback Value was used — which is an empty string unless you set one. See Put object metadata into an HTML component.

The calendar is empty

The calendar does not report a failure to the user. It logs Failed to retrieve events for '<event title>' and returns no events, so the application log is where the reason is, and the line names the event type that failed.

The usual causes, in order:

From is not set on the event type, or names a property that is not a timestamp.
The event objects fall outside the date range on screen. The search asks for objects whose From is at or before the end of the range and whose To — or From, where no To is configured — is at or after the start.
The event type’s Class narrows it further than intended. Leaving Class empty places no class restriction at all.

The calendar shows every event rather than this object’s

Direct Relationship on the event type is the property that points an event back at the object the portal is showing. Without it there is nothing to filter on, so a portal calendar shows every event of that type in the vault, and events created there are saved with no link back to the object.

It is not needed on a dashboard, which has no object to relate to.

A separate warning, Could Not Set Current Employee, appears when a personal event is created and the signed-in user has no Employee object. The event is still created; the personal property is left unset.

A comment will not post

Unknown author. Check author and user configuration. The signed-in user has no Employee object. CtrlPortals finds it by searching the object type named in employee configuration for one whose User property refers to that user and which is not deleted.

That lookup is cached, and so is the miss: a user found to have no Employee object is remembered that way for an hour. Creating the missing Employee object therefore does not fix the comment straight away, and neither does Cache Update Frequency, which refreshes the list of users rather than the employee each one maps to.

Cannot reply to comments if no Comment & Employee configuration is present. The vault has no comment configuration, so the module is in its fallback mode showing M-Files version comments, which are flat and read-only. Replies and edits need a Comment object type. See Comments.

You can only edit your own comments. Deliberate. Editing is restricted to the author, whatever the user’s M-Files permissions on the object are.

A SQL-backed plot or list will not load

This SQL query is not part of the server configuration. Only queries an administrator has written into the configuration can run, matched on the data source name and the query text together. The client sends the query it was given; if that no longer matches anything the server holds, it is refused.

The everyday cause is an edited query: change the SQL in M-Files Admin and every client still holding the previous copy is refused until it refreshes.

SQL data source 'X' is not configured. The Data Source Name on the widget matches no Name under data source configuration. The comparison ignores case but not spelling.

Two more show up as an empty or broken chart rather than as a message: a Parameter Name has to match the parameter in the query exactly and be unique within it, and the Value Column has to be a numeric column that the query actually returns.

An edit in M-Files Admin will not save

This portal is no longer in the configuration - it was removed while it was open. Reload the configuration.

A portal, dashboard or dashboard group is edited in a node of its own, and that node saves the one item back into the document the rest of the configuration lives in. If the item has been removed since the node was opened — by another administrator, or from the top-level list in the same session — there is nothing left to save it over.

Reload the configuration in M-Files Admin and make the change again. Nothing else in the configuration is affected.

Could not save portal "…": someone else changed it while it was open, and their change and yours touch the same place. Conflicts: …

Since 3.26.9.37, two administrators can edit the same portal or dashboard at once. When both save, CtrlPortals merges the two edits: changes to different settings, different components or different list entries all land. Only the same setting changed to different values on both sides is a conflict, and the message names it, for example Components › “Sales by month” › PlotView › Height: set to “500” by them, set to “300” by you.

Nothing was written. Reload the item and apply your change again.

… the copy you started from is no longer kept

The merge keeps the last ten revisions of each item. More than ten saves happened while your editor was open. Reload the item and apply your change again.

Portals look different after upgrading to 3.26.9.37

CtrlPortals 3.26.9.37 upgrades the stored configuration to version 2.0 the first time it starts, and three changes in that upgrade are visible to users:

Layout. Use Advanced Width, Stackable and Doubling are replaced by one Width per element. Rows that relied on Stackable being off now widen in narrow panes. See Width and reflow.
Event text colour. An event type’s Text color is now optional, and the upgrade removes the old white default. Events on light backgrounds switch to black text.
List editing. Cell editing in list views is off until Allow editing is turned on. See A list view no longer offers editing.

Before the upgrade, CtrlPortals stores a copy of the configuration in the vault. To go back to it, right-click the CtrlPortals node under Applications in M-Files Admin and select the Restore backup from … entry whose reason is the upgrade, such as upgrade 1.0 -> 2.0. The restore backs up the current configuration first. The newest five backups are kept.

A list view no longer offers editing

Since 3.26.9.37, cell editing in a List View is off by default. Turn on Allow editing in the component’s List view section for each list that should show the Edit button and the cell editors. The Multi View has the same switch as List: allow editing, and the table that opens when a user clicks a point in a plot has Drill-down: allow editing.

With editing on, a cell is editable only where the user may edit that object and that property. Automatic and read-only properties stay read-only.

A map visual shows nothing

Map visuals are no longer rendered since 3.26.9.28, which ships the plotting library without its map support. A visual whose type is Map draws nothing and reports no error. Change it to one of the types still supported: bar, pie, line, scatter or indicator.