Adding external notes to Neuro-Feature™ tokens
Each Neuro-Feature™ token has an event log. Notes can be added to this log. If the Neuro-Feature™ token runs a state-machine, the state-machine can process the contents of such notes also.
There are 2 × 2 × 2 types of notes that can be added: Plain text and XML notes can be added, and they can be either by owner or an external source. They can also be personal or public. Personal notes are deleted when the token changes owner. This article describes how a public (to those with access to the token) external note can be added to the Neuro-Feature™ token.
External Sources
To add an external note on the token, you need to be an approved external source. Depending on method used to add the token, this source is typically a User name on the Neuron® hosting the token. This User name, can also be a domain name of the caller, if mutual TLS (mTLS) is used to authenticate the call. If note is added by an XMPP client or Agent API client, the source would be the Bare JID of the client adding the source. In all cases, the source needs to be an approved source, otherwise the note will be discarded.
Methods of adding an External Note
There are multiple ways how a note can be added to a token. If the caller is not the owner of the token, the note will be added as an external token. Some of the methods described allow the Owner to add a note. If this is the case, the note will be added as a normal note, and may be processed differently to an external note.
XMPP Library
You can use an XMPP extension library, such as the NeuroFeatures nuget from TAG. It extends the Waher.Networking.XMPP library using in the Neuron®, LegalLab, IdApp, Neuro-Access, and other projects. Once the XMPP Client is connected, you can use the extension library to add notes to any tokens.
Approved Sources: If adding a note via the XMPP library, the account you use to sign in must either be part of the contract that created the token, or be an approved external source. The token (if running a state-machine) can define what external sources are approved.
Agent API
The Agent API can be used to add notes to tokens in the network. Multiple implementations exist, including an Agent API nuget. Depending on the type of note you want to add, you can use the AddTextNote or AddXmlNote resources to add notes.
Approved Sources: As with using an XMPP Library, the account you use to sign in must either be part of the contract that created the token, or be an approved external source. The token (if running a state-machine) can define what external sources are approved.
NeuroFeatureNotes Nuget
A specific nuget exists for adding external notes to Neuro-Feature™ tokens: NeuroFeatureNotes. The source-code of this nuget is available in the AddNote repository published by TAG. The repository also contains information about the methods to use to add an external note, and what parameters are required.
Approved Sources: The nuget performs an HTTP POST to the Neuron® hosting the token. The request is authenticated using mutual TLS (or mTLS), where the caller provides a valid certificate that can be used to sign the request. To be able to use this method, you need to do the following:
Enabled mTLS on the Neuron® hosting the Neuro-Feature™ token. This is done in the gateway.config file, and then restarting the Neuron®. You need to set mTLS option to Optional at least, for mTLS to be activated for use in HTTP requests.
Create a Role on the Neuron® for users that are permitted to add notes on the Neuron®. The regular expression approving adding of notes specifically is:
+NeuroFeatures\.Notes\.Add\.(Text|XML)Create a User on the Neuron® with the same user name as the domain name in the certificate you want to use. The user needs at least the privileges define in the Role above.
Note: There is no need to specifically in the token approve the external source, if the operator has approved the domain name already, authenticated using mTLS, as described above.
Once the settings have been made, the library can be used to add external notes to tokens on the Neuron®.
Command-Line tool
The AddNote repository contains a command-line tool that can be used to add external notes on tokens. This command-line tool can be used to automate adding notes via script. The repository lists the arguments required to run the tool.
Approved Sources: As the command-line tool uses the NeuroFeatureNotes nuget to add notes, authentication is performed using client certificates and mTLS, and the same steps of configuring the hosting Neuron® is required, as described above.
Script
If running multiple Neurons, you can add an external note using script on one Neuron® on a Neuro-Feature™ token on another Neuron®, using the certificate of the calling Neuron®.
To add a text note, call the following script (on the first Neuron®, via a web-service or the Prompt):
Post("https://DOMAIN/AddNote/TOKEN_ID","ADD THE TEXT YOU WANT TO ADD HERE.",\{\},Waher.IoTGateway.Gateway.Certificate)
To add an XML note, call a similar script, but instead of POSTing a string, POST an XML document (the XML needs to be valid, in accordance with the schema, downloadable from the namespace):
Post("https://DOMAIN/AddNote/TOKEN_ID",<ADD THE XML YOU WANT TO ADD HERE>,\{\},Waher.IoTGateway.Gateway.Certificate)
PS: The Community site adds backslash characters before the start and stop braces in the script examples above. These need to be removed when executing the script.
Approved Sources: The script above performs a POST that will be authenticated using mTLS, as in the examples above. Therefore, the same steps of configuring the Neuron® hosting the token is required, as described above.