Chapter 3
Maintenance
This section details common operating procedures.
Subsections of Maintenance
Server datamodel update
A data model is not fixed in time, it can evolve and therefore be updated, whether from the server or on one or more clients.
Each time the datamodel is modified on the server, its new version is propagated to the clients with its “public” data: each data type is included, with its primary key, the list of its attributes, and the list of its secret attributes. Then some consecutive events are emitted.
Add an attribute to an existing data type
- 👱 Add attribute to server datamodel, reload server
- 💻 Emission of a dataschema event by the server
- 💻 Emission of “modified” events for the concerned entries, with the added attribute and its value
- 💻 Processing of dataschema event by clients: updating their schema. Processing incoming “modified” events: as the attribute is not declared yet in their datamodel, its value is ignored but stored in the complete cache
- 👱 Add attribute to clients datamodel, reload clients
- 💻 Local datamodel update processing by clients: generation and processing of “modified” local events from the complete cache
or
- 👱 Add attribute to clients datamodel so that they can process it when it will be added to the server datamodel, reload clients: ⚠️ datamodel warning “remote attributes don’t exist in current Dataschema”
- 👱 Add attribute to server datamodel, reload server
- 💻 Emission of a dataschema event by the server
- 💻 Emission of “modified” events for the concerned entries, with the added attribute and its value
- 💻 Processing of dataschema event by clients: updating their schema. ✅ No more datamodel warning. Processing incoming “modified” events
Remove an attribute from a data type
- 👱 Remove attribute from clients datamodel, reload clients
- 💻 Local datamodel update processing by clients: generation and processing of consecutive “modified” local events
- 👱 Remove attribute from server datamodel, reload server
- 💻 Emission of a dataschema event by the server
- 💻 Emission of “modified” events for the concerned entries, with the removed attribute. They’ll be ignored by clients
- 💻 Processing of dataschema event by clients: updating their schema
or
- 👱 Remove attribute from server datamodel, reload server
- 💻 Emission of a dataschema event by the server
- 💻 Emission of “modified” events for the concerned entries, with the removed attribute
- 💻 Processing of dataschema event by clients: updating their schema. ⚠️ datamodel warning “remote attributes don’t exist in current Dataschema”. Processing incoming “modified” events
- 👱 Remove attribute from clients datamodel, reload clients: ✅ No more datamodel warning
Modify the value of an attribute (by changing its Jinja filter, or its remote attribute from the data source)
- 👱 Modify attribute in server datamodel, reload server
- 💻 Emission of “modified” events for the concerned entries, with the modified attribute new values
- 💻 Processing incoming “modified” events
Add an existing attribute of a data type to secrets_attrs
- 👱 Modify secrets_attrs in server datamodel, reload server
- 💻 Purging attribute from server cache
- 💻 Emission of a dataschema event by the server
- 💻 Emission of “modified” events for the concerned entries, with the “added” attribute and its values
- 💻 Processing of dataschema event by clients: updating their schema, purging attribute from their cache
- 💻 Processing incoming “modified” events
Remove an existing attribute of a data type from secrets_attrs
- 👱 Modify secrets_attrs in server datamodel, reload server
- 💻 Emission of a dataschema event by the server
- 💻 Emission of “modified” events for the concerned entries, with the “added” attribute and its values
- 💻 Processing of dataschema event by clients: updating their schema
- 💻 Processing incoming “modified” events
Add a new data type
- 👱 Add data type to server datamodel, reload server
- 💻 Emission of a dataschema event by the server
- 💻 Emission of “added” events for each entry of added data type
- 💻 Processing of dataschema event by clients: updating their schema. Processing incoming “added” events: as the data type is not declared yet in their datamodel, its entries are ignored but stored in the complete cache
- 👱 Add data type to clients datamodel, reload clients
- 💻 Local datamodel update processing by clients: generation and processing of “added” local events from the complete cache
or
- 👱 Add data type to clients datamodel so that they can process it when it will be added to the server datamodel, reload clients: ⚠️ datamodel warning “remote types don’t exist in current Dataschema”
- 👱 Add data type to server datamodel, reload server
- 💻 Emission of a dataschema event by the server
- 💻 Emission of “added” events for each entry of added data type
- 💻 Processing of dataschema event by clients: updating their schema. ✅ No more datamodel warning. Processing incoming “added” events
Remove an existing data type
- 👱 Remove data type from clients datamodel, reload clients
- 💻 Local datamodel update processing by clients: generation and processing of consecutive “removed” local events
- 💻 Purging local cache files of removed data type
- 👱 Remove data type from server datamodel, reload server
- 💻 Emission of “removed” events for each entry of removed data type
- 💻 Purging cache files of removed data type
- 💻 Emission of a dataschema event by the server
- 💻 Processing incoming “removed” events by clients: all are ignored
- 💻 Processing of dataschema event by clients: updating their schema
- 💻 Purging remote cache files of removed data type
or
- 👱 Remove data type from server datamodel, reload server
- 💻 Emission of “removed” events for each entry of removed data type
- 💻 Purging cache files of removed data type
- 💻 Emission of a dataschema event by the server
- 💻 Processing incoming “removed” events by clients
- 💻 Processing of dataschema event by clients: updating their schema. ⚠️ datamodel warning “remote types don’t exist in current Dataschema”
- 💻 Purging remote cache files of removed data type
- 👱 Remove data type from clients datamodel, reload clients: ✅ No more datamodel warning
- 💻 Purging local cache files of removed data type
Change the primary key attribute of a data type
DANGER - Here be dragons
This is the riskiest datamodel update, as there may be links between data types, using the primary key as a foreign key.
This means that you’ll need to update every data type at once, without missing anything.
You should really consider doing this update on a test environment before doing it in production, because if something fails, your clients could be permanently broken.
Prerequisites
The attribute(s) to use as new primary key must already exist in your server datamodel, and their value must already have been propagated and exists in clients cache.
Trashbin retention may delay the Datamodel update
The new primary key MUST exist in every entry of its data type before updating the datamodel. If trashbin is enabled on some of your clients, the new primary key attribute might be missing from trashed entries.
The safest way to handle this is to add the attribute to your server datamodel and delay the primary key change at least to one day + as many days as the highest trashbin_retention value of all your clients.
If you don’t handle this this way, the client will purge all trashed entries that doesn’t contains the value of the new primary key attribute(s) as if the trashbin_retention delay was expired.
Updating
- 👱 Update all data types in server datamodel, reload server
- 💻 Updating changed primary keys in cache files on the server
- 💻 Emission of a dataschema event by the server
- 💻 Processing of dataschema event by clients: purging trashed entries that are missing the new primary key, updating their schema, updating changed primary keys in cache files and error queue
Client datamodel update
A data model is not fixed in time, it can evolve and therefore be updated, whether from the server or on one or more clients.
Each time the datamodel is modified on a client, the client will generate appropriate local events to reflect the data changes on targets.
It may notify about datamodel warnings if some remote data type or attributes are set in its datamodel, but doesn’t exist in current dataschema received from hermes-server.
Add an attribute to an existing data type
- 👱 Add attribute to clients datamodel, reload clients
- 💻 Local datamodel update processing by clients: generation and processing of “modified” local events from the complete cache
Remove an attribute from a data type
- 👱 Remove attribute from clients datamodel, reload clients
- 💻 Local datamodel update processing by clients: generation and processing of consecutive “modified” local events
Modify the value of an attribute (by changing its Jinja filter, or its remote attribute from the data source)
- 👱 Modify attribute in clients datamodel, reload clients
- 💻 Local datamodel update processing by clients: generation and processing of consecutive “modified” local events
Add a new data type
If its hermesType already exists in dataschema
- 👱 Add data type to clients datamodel, reload clients
- 💻 Local datamodel update processing by clients: generation and processing of “added” local events from the complete cache
If its hermesType doesn’t exists in dataschema yet
- 👱 Add data type to clients datamodel so that they can process it when it will be added to the server datamodel, reload clients: ⚠️ datamodel warning “remote types don’t exist in current Dataschema”
- 👱 Add data type to server datamodel, reload server
- 💻 Emission of a dataschema event by the server
- 💻 Emission of “added” events for each entry of added data type
- 💻 Processing of dataschema event by clients: updating their schema. ✅ No more datamodel warning. Processing incoming “added” events
Remove an existing data type
- 👱 Remove data type from clients datamodel, reload clients
- 💻 Local datamodel update processing by clients: generation and processing of consecutive “removed” local events
- 💻 Purging local cache files of removed data type