Folders
The modeler start page organizes stored diagrams and forms in folders, from 3.0.0. Earlier versions showed one flat list of everything.
Every model lives in exactly one folder. The top level of the start page — Projects — therefore holds folders only, and models appear once you open one.
Existing models
Updating an installation to 3.0.0 creates a folder named General and puts every diagram and form into it, so nothing has to be sorted by hand. See Database Schema.
General is an ordinary folder from then on: rename it, move it or delete it as you see fit. Nothing recreates it.
Your Own Folder
The first time you open the modeler, a folder named after your user ID is created for you at the top level, so there is always a place to store a model. It is created when you open the modeler, not when you log in, so users who never use the modeler get no folder.
Unless you choose another default folder, the start page opens in this folder every time you open the modeler, so you can create or import a model straight away. Projects in the breadcrumb leads to the top level and the other folders. Refreshing the page keeps you where you are: the folder you have open is part of the address.
Apart from that it is an ordinary folder: it is listed by name among the other folders of the top level, and you create, rename, move and delete the folders and models inside it as anywhere else. In the community edition it is not private either: every modeler user sees it and can work in it. In the enterprise edition, from 3.0.0, it is yours: you are its only member until you add others, see Project Members.
Only the folder itself is protected: it cannot be renamed, moved or deleted, and its row offers none of those actions. Administrators, users granted the All permission on the System resource, can do all three, for example to clean up after somebody has left. A user folder that was deleted is created again the next time its user opens the modeler.
A folder that already carries your user ID
If a folder at the top level already has your user ID as its name when you first open the modeler, it is used as your folder instead of creating a second one. It stays unprotected when somebody else created it.
Browsing
The list shows the folders of the level you are on first, then its models. Selecting a folder opens it, and the breadcrumb above the list walks back out again. The folder you are in is the last entry of the breadcrumb and is not a link; the ones before it are.
Default Folder
The star next to the breadcrumb makes the place you are in the one the start page opens when you open the modeler: a project, any folder in it, your own folder, or Projects, the top level. The star is filled while you are in your default folder, and the list marks the default folder with a star as well. Selecting the filled star unsets it, and the start page opens your own folder again.
The default is kept in your browser and for your user only: another browser, or another user of the same browser, has a default of its own. If the default folder is deleted, or you can no longer see it, the start page opens your own folder instead and the default is forgotten.
Refreshing the page keeps the folder you have open; the default only decides where a new visit starts.
Working with Folders
New folder creates a folder in the level you are on: inside the folder that is open, or at the top level when you are on Projects. A name has to be unique among the folders beside it — two folders with one name in one place would be indistinguishable.
Each folder row offers, when it is hovered or focused:
| Action | Effect |
|---|---|
| Rename | Changes the name. The folder keeps its identity, so everything in it stays reachable |
| Move | Moves the folder, with everything below it, into another folder or to the top level |
| Delete | Removes the folder and everything below it |
The folder of a user (see Your Own Folder) offers none of these actions unless you are an administrator.
A folder cannot be moved into itself or into one of its own subfolders, and the destination list leaves those out.
Projects with members
In the enterprise edition, from 3.0.0, a project can have members, and each member a role. What a row offers then depends on your role in its project, and folders and models move only inside their project or, for a folder, to the top level. See Project Members.
Deleting cannot be undone
Deleting a folder deletes the folders, diagrams and forms below it for good — there is no trash to restore them from. The confirmation names how many folders and how many models will go with it; read that count before confirming. Processes already deployed to the engine are not affected: deleting a model in the modeler does not undeploy anything.
Working with Models
Each diagram and form row offers Move, which files it in another folder, and Copy, which puts a copy in the folder you choose.
A process key and a form id are unique within a folder, not across the modeler: the same process may sit in several folders, as two files of it would on disk. A copy into another folder therefore keeps its key, and only a copy into the folder of the original needs a key of its own. The dialog asks for the process key or the form id and offers the original; once you pick the folder the original is in, it offers the key with -copy appended instead. A key you type yourself stays as it is.
Moving a model keeps its identity: its id and its key stay as they are, so links to it and deployments made from it continue to work. Only where it is filed changes. A folder that already holds a model with the same key refuses it: change the key first, or move the other model.
Creating and Importing
New models and imported files are stored in the folder you have open, which is why Import local file, Create BPMN, Create DMN and Create Form are offered only inside a folder and not on Projects. A file dropped on the page goes into the folder you have open. Dropped on Projects, it goes into your default folder; when you have none, or Projects is your default, the modeler asks which folder it goes into.
When an imported file has the key of a model in the folder it is imported into, the modeler asks what to do with it. Choosing Replace overwrites the content of that model. Choosing Rename stores a new model under another key. A model with the same key in another folder is no conflict: the file is stored as a new model in the folder you are importing into.
Keys and Deployment
Several models may share a key, each in its own folder, but the engine keeps one process definition per process key and resolves a form reference by its form id. Deploying any of them adds a new version to what the others deployed. The deploy dialog therefore warns when another model in the modeler uses the key. The warning does not block the deployment, and it names neither the other model nor its folder, as that may be in a project you cannot see.
A diagram that references a form (camunda:formRef) gets that form added to the deployment. When several forms you can see have the form id, the dialog takes the one in the same folder as the diagram, then one in the same project, then the one changed last, and says that several forms matched, so you can check the choice before deploying.
Opening a deployed process in the modeler from the cockpit opens the model with its key that was changed last, among those you can see.
Searching
The search field looks through every folder, not just the one you are in, so a model can be found without knowing where it was filed. A search starts at three characters, and while one is active the folder rows are hidden and a line under the breadcrumb says the results come from everywhere. Clearing the field returns to browsing.
Searching matches the name and the key of a model, not the name of the file it came from. A file imported as invoice.v2.bpmn is found by the process key inside it, not by invoice.v2. Folders themselves are not searched.