CtrlProcesses troubleshooting

Headings here are symptoms — what you see — rather than causes.

A CtrlProcesses deployment has three parts that fail independently: the synchronisation, the viewer, and URL publishing. Knowing which one has stopped is most of the diagnosis.

Check these first

1. Does the application status report an error? M-Files Admin shows the application’s own validation under the vault’s Applications node. A bad credential or a missing organisation id appears there.
2. Are both authentication contexts filled in? The system context drives the synchronisation and the end-user context drives the viewer. One working and the other not produces a deployment that half works.
3. Do the operations have a schedule? With no triggers configured, neither the synchronisation nor the reconcile runs — including at application startup. This is deliberate and it is the most common reason nothing happens.
4. Is the licence valid? Without one the background operations do not run.

The synchronisation runs and creates duplicates

The Elements object id property is how a run recognises what it created last time. Duplicates mean the match failed.

• The property is not mapped on that entity. Every entity mapping needs it.
• Somebody edited the value. It is written by the synchronisation and read by it; a hand-edited id no longer matches anything in Elements, so the next run creates a new object. Make the property read-only or hide it from the metadata card.
• The mapping’s object type or class changed. Objects created under the old mapping are not found by the new one.

Removing the duplicates is a vault clean-up; the application will not merge them.

A run stopped early

The run spent its Maximum retry wait budget on rate-limit back-off, retries and pacing combined. It reports this and stops.

Nothing is lost. The next run resumes the sections the previous one did not finish. A run stopping early every time means either the budget is too small for the size of the import or the Elements tenant is rate-limiting hard — raise the budget before touching the minimum request interval.

Zero removes the budget rather than raising it

Setting Maximum retry wait to zero removes the budget entirely, which allows a run to wait indefinitely on a background thread. Raise it rather than removing it.

Everything is slow

Minimum request interval is a floor on the gap between API calls, not a delay to add to each one. A non-zero value here slows every run whether or not Elements is rate-limiting, and the synchronisation already backs off on its own when it needs to. Set it to zero unless the tenant has a stated limit.

The viewer is empty

No object click mapping matches. The mapping says which class opens which diagram, and where the diagram id is read from — the object itself, or an object it refers to. A class with no mapping shows nothing.

The diagram id is missing on the object. The mapping resolves correctly and finds nothing to open.

The end-user context is not authenticating. The synchronisation uses the system context and keeps working, so this looks like a viewer-only problem. It is a credential problem.

The user group has the feature switched off. User group mappings decide what each group sees; the mapping marked default covers everyone with no specific mapping.

The diagram number does not match the object

Both can be right. Master shows the current state in Elements.cloud; latest synced release shows the release the synchronisation last applied. Reorganising master renumbers diagrams while leaving their names unchanged, so the two disagree on numbers and agree on names.

Set the viewer to latest synced release where diagram numbers are quoted on objects or in reports. Use master where people need to see work in progress and know that they are.

No lights or flags on the activities

Activity status lights need a data table of a configured kind attached to the activity in Elements.cloud. An activity carrying no such table gets no light, and that is the intended behaviour rather than a failure.

Reference model flags appear only for reference models with an entry in the flag list. The list is the opt-in as well as the styling, so an activity mapped to a standard with no entry is not flagged.

Objects were deleted that should not have been

Deletion is the reconcile operation, not the synchronisation, and what it does to an object whose Elements counterpart has gone is configurable. Check the deletion strategy before re-enabling it, and give reconcile a much less frequent schedule than the import.

An object that disappeared from Elements.cloud temporarily — during a reorganisation, for instance — looks the same to reconcile as one that was deleted deliberately.

An object that came back in Elements.cloud stays archived

With the Archive deletion strategy, an object that reappears in Elements.cloud is moved to Restored state, if one is set. Leave it empty and the object stays in the archive state, and the log records a warning for each one. Set Restored state under Deletion to a state of the archive workflow that brings the object back into use.

With the Flag strategy there is nothing to set: the ‘Deleted in Elements’ property is cleared when the object reappears.

Links are not appearing in Elements.cloud

URL publishing is driven by workflow states rather than by a schedule. Check that the state the object entered is one of the states mapped as publishing, and that the property storing the published link id is mapped — without it, each publish creates another link instead of updating the existing one.