Bug Fixed: Misspelling in State-Machine interface

A relatively consequential misspelling has been corrected in the State-Machine object model on the Neuron®. The property that holds the XML definition of the state-machine was mistakenly named XmlDefinnition. It has now been corrected to XmlDefinition, from build 2023-09-25 of the Neuron®. This change may have some consequences:

• Serialization and deserialization of state-machine objects during Loading and persistance is done automatically. In this process, the old, and now obsolete XmlDefinnition property is automatically transformed into the new XmlDefinition property, if this persistance or loading is done in a typed manner, i.e. knowing what type of object is being processed. This is the default case when processing state-machines and their events, in normal processing.

• The automatic conversion is not performed if untyped access to the state-machine object is performed. This can be done, for instance, when processing content using SQL or SPARQL queries, accessing the collection directly, without referencing specific types (i.e. using generic types).

Consequences

This change can have unintended consequences for all untypes access to the State-Machine object model. In the Neuron®, this only happens during backup, import or export of the database, or from third-party applications performing untyped access to the database. We are aware of no such third-party service that presents the state-machine XML definition, so no unintended consequences are expected.

Note: This misspelling does not affect the smart contracts and Neuro-Feature tokens creating the state-machine. It only relates to the internal object model for maintaining a running state-machine on the Neuron®.

#bug, #fixed, #state-machine

Note commands in state-machine neuro-feature tokens

One way to interact with state-machines defined by Neuro-Feature™ tokens can be done using notes. Such notes can be either text or XML, and they can be either logged by the owner of a token creating the state-machine, or by approved external sources. All notes are logged also to the Neuro-Ledger™, for transparency reasons. For XML-tokens, an additional XML-validation is performed, before accepting a note: The XML must use publicly downloadable schema-files, and the XML must be valid, in accordance with these schema files. Personal notes are deleted, if the tokenⓈ change owner.

Until build 2023-09-22 of the Neuron®, owners and external sources had to know the syntax of such notes, to interact with the state-machines. The token, and underlying state-machine, can now instead describe what notes are available, under what contexts they are available, and how they are formed, in a way that is both understandable by machines, and humans. It is therefore possible to create user interfaces automatically and generatively, directly from the state-machine definition. LegalLab has also been updated to support such note commands, as have the corresponding example contracts in the repository.

Example: Digital Sensor Twin

The DigitalSensorTwin example contains several context-specific note commands. The owner can poll the sensor, pause reading, resume reading, reconfigure the digital twin, and terminate it. Some of these commands are parameter-less, others are parametrized. Parametrized note-commands require the user to fill in a form before the note can be logged. All XML-based commands use a corresponding schema file, available in the repository, and also downloadable from the corresponding namespace URL.

In the following example, LegalLab is used to create a digital sensor twin of a weather station, available at the XMPP address concon.openweathermap@lab.tagroot.io.

Once the contract has been created and signed, the token is created, together with the state-machine of the digital twin of the sensor. The corresponding token appears in the Tokens tab. Note commands, defined in the token itself, will now appear in both the context menu, as well as in the token details view.

Parametrized note commands

As an example of a parametrized note command, let’s review the Reconfiguration command in the digital sensor twin, and how it is defined:

The parameters are defined in a similar manner, as contract parameters. An optional note context script can be added to tell the client under what conditions the command is visible. The script is run on the client, is checked to be safe, and can include references to the state or internal variables of the state-machine to evaluate if the command should be visible or not. The script should return a Boolean value. Anything else, will hide the command.

Once the command is executed, the note generation script is executed, and should return either a text string (for text notes) or XML (for XML notes). Anything else is ignored. If text or XML is returned, this is the basis for the note that will be logged.

Note: To avoid confusion as to what is XML, and what is script, it may be a good idea to always embed script in CDATA constructs, as shown in the example. This becomes especially important, if the script also contains XML, as in this case.

Parameter-less note commands

If a note command does not require parameters, simply skip the Parameters section in the definition. Such commands may still be context-sensitive, for instance, be based on the current state of the state-machine, or its internal variables. You can try such commands by testing the Pause and Resume commands of the digital sensor twin. The Pause command is only available in the active state, while the Resume command is only available in the Paused state.

State-Machine Schema

The most recent schema for State-Machines is always available by downloading the schema from its URL, which is the same as its namespace: https://paiwise.tagroot.io/Schema/StateMachines.xsd. It contains the details, what attributes are available, as well as what is required and what is optional.

#neuro-feature, #new, #state-machine, #legallab

Bug Fixed: State machines did not persist the beforeActionScript attribute

State-machines using the beforeActionScript attribute on action reference nodes, such as event handlers, have lost their corresponding attribute values after restart. The reason is that the attribute value was not persisted.

Cause

The root cause of this is that the property was declared incorrectly. To be persisted, an attribute needs to have a public get and set method available, for the persistance layer to be able to persist it. Persistence is implicit, and no code is written explicitly to persist or load objects. Instead, the persistence layer relies on the declaration of the properties to persist. In this case, this particular property lacked such get and set methods.

Background

The beforeActionScript attribute was introduced to provide a means to re-use actions for different types of events. It allows the event handler to customize the execution of the action, by (for instance) providing variable declarations. (In such cases, the before-action script would work as assigning argument values in a function or method call in procedural or object-oriented programming languages.)

Tests

The problem was not detected in unit tests, since these are implemented in such a way to create new state machines for every test, to not rely on earlier execution, and therefore, they did not test more than the operation (which worked), and that persistance occurred without error. The tests missed that this particular attribute was lost once loaded after server restart.

Fix

The attribute is now declared properly, and value is persisted.

Review

After a review of the entire state machine model, it is concluded that this attribute was the only attribute that lacked a proper declaration.

Affected tokens

This problem affects generated tokens on Neurons with a build-time before 2023-09-21, if and only if they used the beforeActionScript attribute. After update, new tokens generated will persist the attribute correctly. Upgrading your Neuron® to a newer version, will not resture the attribute value.

Repair

A new method has been added to the State-machine object: ReparseDefinition(). As the original XML of the state-machine is available (and kept immutable in the token), the lost attribute can be regained by calling the ReparseDefinition() method on each state-machine, resave the objects, and then restart the Neuron®, for the changes to take effect.

Following is some script you can execute in the script prompt to re-parse all state-machines on the Neuron®. It will return a vector of all state-machine-IDs processed. Depending on the number of state-machines, complexities of the models, etc., execution of the script may take some time. (You can adapt this script if you want to apply it only to specific state-machines.) Make sure to take a backup before executing the script.

preview("Loading state-machines. This may take some time.");
Machines:=select * from StateMachines;
[foreach Machine in Machines do
(
	preview("Processing "+Machine.StateMachineId);
	Machine.ReparseDefinition();
	UpdateObject(Machine);
	Machine.StateMachineId
)]

Note: All changes to the operational state of the state-machine, as well as script executed via the script prompt, will be logged, both to the event log, as well as to the Ledger.

Note 2: If expecting many state-machines to be processed, you can use the TOP and OFFSET operands in the select statement, to paginate the processing into chunks.

Note 3: Keep the event log sniffer open while processing the script, to check for any unexpected events.

Note 4: Test this script in your lab/development environment first, and consider whether you need the update in your production environment or not, before applying the change. You can also modify the script to only process the state-machines you decide are important to update, to minimize any risks when performing the update.

#bug, #fixed, #neuro-feature, #state-machine