Field Definition Drafts
- Bart Quintens
- Alexis Rombaut
- An De Moor
This feature is part of the release 24.2
Introduction
Field definition drafts are changes to field definitions which the user can prepare without any impact on the actual published definitions used by the system. The user then submits the draft field definitions for publication, and the system processes them in the background and ultimately publishes them.
Status
The property status describes the phase in which the field definition currently is
Status | Description |
|---|---|
| Field definition has been created, updated or deleted but has not been published yet. |
| After submitting the field definitions, depending on the type change (see below), it takes some time before the processsing is finished. |
| The field definition is now published and applied to the system as a whole |
The status is the property of a top field definition, shared with all its children.
Restrictions
When changes to field definitions are processing in the background, it will not be possible to edit the drafts as of version 24.2. In a future version this restriction will be relaxed.
The database tables for published field definitions (field_definitions, field_translations and field_definition_enum_values) are no longer allowed to be edited manually or used in database migrations. Ignoring this will result in broken indices. Use the field definition API instead.
Actors
We have 3 types of field changes to allow the 3 different actors to change fields with minimal interference from each other. Only the changes from 1 actor will be processed and ultimately published when submitting field definitions.
Initiator | Context |
|---|---|
| Users who want to modify fields do so via the rest API or the module Settings & Managment. The rest API automatically sets the initiator to |
| For migrations, we need to set the |
| When the system needs to make changes (for instance when creating record types), it sets the initiator to |
Type of change
When a change happens, the status of the field definition changes to Draft. The action field is set to one of the following according to the action the user does:
UpdateCreateDelete
The status of the parent(s) is changed to Update. In case of deletion, the status of the children is updated to Delete.
Submitting/publishing the drafts
When the changes are completed an action called PublishDrafts can be called on the field definitions. The status of the fields is changed to Processing (only those changed by the initiator). The system then determines based on the changes what needs to happen to the index using one of the following action types. See Change action types for a complete reference. Each action type corresponds with a subaction that is returned as a result of the action call. If necessary, the allowed subactions can be passed as a property of the action call. If a subaction is not allowed, a ConflictException will be thrown.
Action Type | Subaction | Description | Duration |
|---|---|---|---|
Rebuild |
| Full rebuild of the index. Should happen on a separate index. The changes are published when the reindex is successful. During this rebuild, the draft definitions need to be used when fetching the records. | Very long |
Reindex |
| A reindex of the existing index. This requires the definitions to be published immediately. (Via patch of field definitions in solr). | Long |
Update |
| The changes don’t require a reindex so they are published immediately. (Via patch of field definitions in solr) | Short |
Nothing (only publish) |
| The changes are published immediately in the database. Examples of changes are enum values and translations. | Instant |
Publication
The field definitions status is changed to Published when all changes are applied. The drafts are updated to published and the changes are applied to the field_definitions table.
Benefits
Ability to prepare multiple changes to field definitions without affecting the customer
When changing a field for a specific index, only that index will be affected during publication
When changing a field, only the changes for that field and the top field it is part of will be patched during publication
Migrating field definitions
Only support users are currently allowed to migrate or create new field definitions. See https://mediahaven.atlassian.net/wiki/spaces/DEVELOPMENT/pages/4223991813 for details.
Reset the drafts
When in case of asynchronous errors the publication should be retried, an action called ResetDrafts can be called on the field definitions. As a result, field definitions with status Processing are reset to status Draft.
Note that this is a recovery action and should only be used when the publication is stuck.
Appendix: Actors acting on the drafts
Â