Sketches and publishing – how changes go live¶
Changes to the configuration of nexxcite are collected in a sketch first and take effect for all users only when the sketch is published. This chapter describes how sketches work, how to publish them, how to undo a published sketch, where every publish is recorded and how to move changes between installations.
1. Sketches at a glance¶
A sketch is a draft: a list of changes to definitions that have not been published yet. While a sketch is open, every definition you save is saved into the sketch and not into the running configuration.
| Property | Behaviour |
|---|---|
| Visibility | You see the configuration including the changes of your open sketch – everywhere, in the Admin Studio and in the application. Other users see the published configuration until the sketch is published. |
| Saving | A sketch saves itself. Every change is stored the moment you save it in an editor. There is no separate save button. |
| One open sketch | Each user has at most one open sketch at a time. Several users can open the same sketch and work in it together. |
| Publishing | All changes of the sketch take effect for all users in one step. |
| Undo | A published sketch can be rolled back with a new sketch that restores the previous state. |
| History | Every publish is recorded with the state it brought, see section 5. |
2. Working with a sketch¶
The sketch control sits in the header of the Admin Studio and – while a sketch is open – in the top app bar of the application.
Creating or opening a sketch¶
Without an open sketch, the control shows "No sketch" and its menu says "Changes go live immediately". The menu offers:
| Entry | Effect |
|---|---|
| "Create sketch" | Creates a new, empty sketch and opens it. |
| "Open sketch" | Opens one of the existing sketches. |
| "Reopen last sketch" | Opens the sketch you worked on last, if it has not been published. |
| "Import sketch" | Creates a new sketch from a sketch file, see section 6. |
Sketches are also listed in the Admin Studio under System → Sketches, where they can be opened with "Open".
While a sketch is open¶
- The save buttons of the editors read "To Sketch" and "To Sketch & Close".
- In the Admin Studio, the header is coloured differently, and every definition the sketch changes is shown in italics with a pencil.
- The menu of the sketch control lists the changes of the sketch with their kind (new, changed, deleted). A change can be removed from the sketch there; the definition then stays as it is in the running configuration.
- A click on the name of the sketch renames it.
- The menu also offers "Download" (export, see section 6), "Close sketch" and "Publish".
One change per definition¶
A sketch holds at most one change per definition. Saving the same definition again replaces the target state of that change; the sketch remembers the state the definition had before the sketch first changed it. This state is what a rollback restores.
Closing a sketch¶
"Close sketch" closes the sketch for you. It stays stored and can be opened again later. Changes you make afterwards are no longer collected in it. A sketch that has no changes and was never published is deleted when it is closed, so that no empty sketches pile up.
3. Publishing¶
"Publish" asks for confirmation and then makes all changes of the sketch effective for all users. A progress dialog shows the changes as they are applied.
- Before publishing, the sketch collects the changes that other users or browser tabs have saved into it, so exactly the stored sketch goes live.
- Changes to entities and fields change the database. A new field adds a column, a new entity adds a table, a deleted entity removes its table. On large tables this can take a while.
- If the database change of an entity fails, that entity is not published. All other changes of the sketch are live. nexxcite names the entities concerned, and the sketch stays open, so it can be published again once the cause is fixed.
- A sketch can be published more than once, and the same sketch can be published on several installations. Database changes of entities that already exist – because an earlier publish made them, or because a previous attempt stopped halfway – are recognised and not made a second time.
- A change that deletes a definition which no longer exists is not an error: there is nothing left to do. nexxcite tells you how many such changes there were.
- After a successful publish, the sketch is closed and marked as published. It can be opened, changed and published again.
- Every publish – also one where not everything went live – is recorded in the sketch history (section 5).
Changes without a sketch¶
By default, definitions can only be saved while a sketch is open. Without one, the editors offer no save button.
The setting "Allow changes without Sketch" in the Admin Studio under System → Settings allows saving without a sketch. Changes saved this way take effect immediately for all users. Use it with care – it bypasses the review that sketches provide.
Some definitions can always be changed without a sketch, because they are part of the administration of the installation rather than of the application: global settings, sketches, global values, users, roles, credentials and API access.
4. Rolling back¶
A rollback is a new sketch that brings definitions back to an earlier state. Nothing changes until it is published – review it first. There are two ways to create one:
- In the Admin Studio under System → Sketches, "Rollback" reverses a whole sketch: every definition it published goes back to the state it had before the sketch first went live on this installation.
- In the sketch history (section 5), "Roll back this publish" reverses a single publish: every definition goes back to the state it had right before that publish.
What a rollback does depends on what the definition looked like on this installation before the publish, not on what the sketch said:
| Before the publish | Change in the rollback sketch |
|---|---|
| The definition did not exist, the publish created it | Definition deleted |
| The definition existed and was changed | Definition restored to its earlier state |
| The definition existed and was deleted | Definition restored |
| The definition was already deleted, the publish had nothing to do | No change |
A definition that existed before the publish is never deleted by its rollback – also not when the sketch was imported from another installation and lists the definition as new.
The rollback sketch is marked as "Rollback" and is published like any other sketch. Rolling back changes to entities changes the database again: a field that the original sketch added is removed, including its data.
Sketches that were published before the sketch history existed are rolled back from the sketch itself: from the state each definition had before the sketch first changed it.
5. Sketch history¶
The Admin Studio under System → Sketch History lists every publish of a sketch on this installation, newest first.
| Column | Shows |
|---|---|
| Graph | The line on the left is the configuration of the installation. Every sketch has a line of its own: it starts where the sketch was created and joins the main line at every point where the sketch was published. Sketches that were worked on at the same time run side by side; a long line means a sketch took long from creation to publish. A sketch during whose work nothing else was published has no line of its own – its publish is a dot on the main line. A ring instead of a dot marks a rollback. |
| Name | The name of the sketch at the time of the publish, with the marks "Rollback", "Partially published" (not every change went live) and "Publish 2", "Publish 3", … for a sketch that was published more than once |
| Published / created | When and by whom the sketch was published, and when it was created |
| + ~ − | How many definitions the publish created, changed and deleted on this installation |
| Hash | The beginning of the content hash, see below |
A click on a publish opens its details: the changes with what the sketch said (create, update, delete) and what the publish actually did on this installation, and three actions:
| Action | Effect |
|---|---|
| "Open this state" | Opens a new sketch with the changes exactly as they were published – also when the original sketch was changed afterwards. Use it to look at an earlier state, to continue from it or to publish it again. |
| "Roll back this publish" | Opens a new rollback sketch for this publish, see section 4. |
| "Compare with live" | Shows for every definition whether it is still live exactly as this publish left it, was changed since, or no longer exists – and which later publishes changed or deleted it. For a definition that changed, it names the publish its current state comes from, or says that the current state does not come from a recorded publish (it was changed without a sketch). A click on a later publish opens it. |
Both actions that open a sketch ask first whether your current sketch may be closed, like opening any other sketch. They need the permissions "Create sketch" and "Add sketch".
Content hash¶
Every publish carries a content hash: a fingerprint of the definitions the sketch brings and the state it brings them into. Two publishes with the same content hash – on this installation or on another one – bring exactly the same definitions in exactly the same state. The details of a publish list the other publishes of the same state.
The hash does not depend on when, by whom or on which installation a definition was created or last changed. Secrets such as passwords and access tokens are not part of it, because every installation uses its own; two installations whose definitions differ only in their secrets have the same hash.
6. Moving changes between installations¶
A sketch can be moved from one installation to another, for example from a test system to the production system.
- Open the sketch in the source installation and choose "Download" in the menu of the sketch
control. The browser saves a sketch file (
.nxs). - In the target installation, choose "Import sketch" and select the file. nexxcite creates a new sketch with the changes of the file and opens it. You become its owner.
- Review the sketch and publish it.
A definition that the file lists as new but that already exists in the target installation – because the sketch was imported before, for example – is shown as changed. Its rollback restores it instead of deleting it. For definitions the sketch changes, the imported changes keep the state "before the change" from the source installation; once the sketch is published, the sketch history knows the state of the target installation, and rollbacks are built from that.
7. Permissions¶
| Permission | Allows |
|---|---|
| "Create sketch" | Creating a new sketch |
| "Add sketch" | Opening an existing sketch |
| "Save sketch" | Renaming a sketch and removing changes from it |
| "Publish sketch" | Publishing |
| "Import sketch" / "Export sketch" | Importing and downloading sketch files |
| "Delete sketch" | Deleting a sketch in the sketch management view |
| "Open Sketch Manager" | The collection System → Sketches |
| "View sketch history" | The page System → Sketch History |
Saving a definition into a sketch additionally requires the permission to edit that definition.
8. Limitations¶
- Changes to role assignments are part of the sketch and are published with it, but they are not listed in the menu of the sketch control and can therefore not be removed there individually.
- When "Allow changes without Sketch" is on, a failed database change of an entity is only written to the log. Check the entity afterwards. Changes saved without a sketch are not part of the sketch history.
- The sketch history starts with the version that introduced it. Earlier publishes are not listed.
- "Compare with live" compares the definitions only; it does not check the database tables of entities.
- Which later publishes changed a definition is known for publishes from this version on.
- The graph of the sketch history only covers the loaded publishes. A sketch created before the oldest loaded publish runs off the end of the list; "Load older publishes" continues it.
9. Recommended order of work¶
When a change needs several definitions, create them in this order within one sketch. Each step can use what the previous one created, because the sketch already shows it:
- Data – entities, fields, relationships.
- Logic – expressions, queries, business rules.
- User interface – forms, grids, lists.
- Triggers – buttons, scheduled actions, event rules.
10. Frequently asked questions¶
A user reports that they do not see a change I made. Check whether the change is still in your open sketch. Until it is published, only users who have the same sketch open see it.
Can two administrators work in the same sketch? Yes. Both open the sketch; each one's changes are stored in it and become visible to the other.
Do I lose my changes if I close the browser? No. Every change is stored in the sketch when it is saved in the editor. The sketch stays open for you and is there again when you sign in next time.
How do I find out whether a sketch is already on another installation? Compare the content hash of its publish in the sketch history of both installations. The same hash means the same state.
What does the AI assistant do with sketches? It saves its changes into your open sketch and creates one if none is open. It never publishes. You review and publish its changes like your own.