Set up CtrlProcesses

By the end of this section Elements.cloud processes are objects in the vault, and opening one of them shows its diagram in the M-Files client.

Time: three to four hours for a first deployment. Most of it is building the vault structure the synchronisation writes into.

Who you need: someone with administrative access to the vault, and someone who can issue Elements.cloud API credentials for two contexts and knows the organisation identifier.

Before you start

• An Elements.cloud organisation, its identifier, and credentials for two API contexts — one for background work and one for operations on behalf of a signed-in user.
• A vault running M-Files 23.6.0.0 or later, with clients on 20.12.0.0 or later for the viewer.
• The CtrlProcesses .mfappx file and its .lic licence file.
• An agreed window for a vault restart.
• A decision about which Elements.cloud entities the vault actually needs. Bringing in all seven kinds is the fullest deployment, not the required one.

Steps

1. Install the application and its licence.

   Follow Install a vault application, then Install a vault application licence. One package installs both the server application and the client extension that draws the viewer.

   Check: CtrlProcesses appears under the vault’s Applications node and the vault has been restarted.

2. Enter the organisation id and the two credential sets.

   The Organization ID identifies the Elements.cloud team this vault connects to. Fill it in along with both authentication contexts before configuring anything else.

   Check: the application status in M-Files Admin reports no error. A credential that does not authenticate shows up here, rather than as an empty viewer later.

3. Build the vault structure.

   Create the object types, classes and properties the synchronisation will write into. Each entity needs at least an object type, a class and the text property that stores the Elements.cloud id. See Vault structure.

   Check: you can create one of each object by hand, and the Elements object id property is hidden or read-only on the metadata card.

   Start with one entity

   Configure releases, or process maps, alone and run the synchronisation. Every mapping mistake shows up on the first entity, and configuring all seven before the first run means finding seven copies of the same mistake.

4. Configure the synchronisation.

   Map each entity to its object type, class and properties. Leave the schedule empty for now — with no triggers configured the operation does not run automatically, which is what you want while the mappings are still changing.

   Run it by hand and look at the objects it creates.

   Check: objects appear with the right class, the Elements object id property is populated on each of them, and a second run updates them instead of creating duplicates.

5. Set the schedules.

   Give the synchronisation a schedule, and the reconcile operation a separate, less frequent one. Reconcile is the operation that deletes; running it less often than the import is deliberate. Decide the deletion strategy before enabling it.

   Check: both operations show their next run time, and a scheduled run produces the same result as the manual one.

6. Configure the person and resource sections.

   The person configuration is how CtrlProcesses finds the object representing the signed-in user, which it needs before it can create objects on their behalf. The resource configuration is how resource details are read for display.

   Check: your own M-Files account resolves to an employee object through the property named here.

7. Configure the viewer.

   Set where the viewer tab appears, then the object click mappings — which class opens which diagram, and where the diagram id is read from.

   Choose the diagram version deliberately: master shows the current state in Elements, latest synced release shows the release the synchronisation last applied. They renumber differently; see the note in About.

   Check: opening an object of a mapped class shows its diagram in the viewer tab.

8. Add the per-group features, lights and flags.

   User group mappings decide what each group can do in the viewer and which diagram they see first. Activity status lights and reference model flags decide what is drawn on the boxes — the reference model flag list is also the opt-in, so only the standards with an entry appear.

   Check: a user in a mapped group sees the features that group should have, and a user in no mapped group gets the default mapping.

9. Configure URL publishing.

   Skip this step if the vault does not publish links back to Elements.cloud.

   Map the workflow states that publish, mark published and retire. Point the publisher at the text property that stores the published link id, so later versions update the link instead of creating another one.

   Check: moving a document into the publish state creates one link in Elements.cloud, and a second version updates it rather than adding a second.

If something goes wrong

See Troubleshooting. The most common first-deployment problem is that neither operation has a schedule: with no triggers configured they do not run at all, including at application startup.