Aeonics Modules

Introduction

This documentation is intended for developers, system administrators, devops, fullstack engineers or whomever has sufficient background knowledge to understand it. It assumes that prior knowledge about the overall Aeonics system.

The content of this guide is protected by intellectual property rights and is subject to the Aeonics Commercial License Agreement. The information contained in this documentation is provided as-is without any guarantee of correctness nor any other sort, it is provided in good faith and is regularly checked and updated. If some content is not clear, outdated or misleading, please let us know and we will try to fix it. Some fine internal details are voluntarily omitted from this guide, if you need more information about a specific aspect, please contact us.

The form and language used in this guide is non-formal and intended for trained professionals, therefore some technical details may be omitted and/or the examples provided may not work or compile as-is. This guide is thought to be used along the official javadoc that include the specifics of every class and method of the Aeonics SDK. If you see ways to improve this guide or if you believe some notions would benefit from more details, please let us know.

The sections used in this documentation are organized in alphabetical order whenever possible. The structure is identical for each module.

Conventions

In this document, you will encounter different notations. Words highlighted in blue or orange are special keywords that are important. Other words with a grey background means that it references a technical term or a code-specific keyword.

There are also some code samples or configuration bits that are displayed in separate blocks. The color and header of the block provides some context on how to read the content.

This block type contains JSON information

This block type contains command lines to run in a shell or prompt window

This block type contains Java code

This block type contains the configuration information about a specific item type

This block type contains other unspecified information

This documentation is constantly evolving, so sections or paragraphs highlighted in yellow means that some additional content should be delivered soon...

Next steps

This documentation lists the specific configuration parameters and detailed behavior of all officially supported modules. Additional documentation and next steps are :

Github: Some code samples and other material are publicly published on Github.
Javadoc: The official Aeonics SDK javadoc.
Technological Overview: The overview of core principles and terminology.
Developer Guide: The main documentation about the context and the global system principles.
Tutorials: Some tutorials and code samples to get started quickly.
Aeonics Frontend Framework (AFF): Aeonics uses its own lightweight frontend single page application framework. You can reuse this framework to build your own applications.

Parameter substitution

In the item configuration, you will encounter the {{content.property}} notation. This is a way to substitute dynamically message properties at runtime.

For instance, when the following item config is used

{
	"text": "Hello {{content.name}}"
}

And the following message is being processed

{
	"metadata": { ... },
	"content": {
		"name": "Diego",
		...
	}
}

Then the output will be Hello Diego because the matching message property is substituted in the item configuration.

The substitution is only possible when it is documented so, because the underlying code must account for this option. In order to perform a substitution in your own item, you can use the aeonics.util.StringUtil class:

String text = StringUtil.compositeReplace("Hello {{content.name}}", message.source());

Caution, it may be misleading at first to do the distinction between the {{}} notation and to simply use the property name (or key). When an item requires a plain message property and not a string substitution, you should only mention the name of the desired property. If you do not specify the leading content. or metadata., then the property is taken from the content by default. The same example as above would be:

{
	"key": "name" // same as "content.name"
}

String text = "Hello " + message.get("name");
// same as :
String text = "Hello " + message.get("content.name");

Core

Description

{
	"name": "core"
	"dependency": []
	"shared": true
}

The core module is part of the Aeonics SDK, it provides the foundation of the system:

the security layer
the publish/subscribe mechanism
the data, item, registry and factory mechanisms
the basic ingress, regress and egress handlers
the internal scheduler and asynchronous events mechanisms
the basic network management
the snapshot, config, storage and data source mechanisms

When the system runs without a snapshot, it will initialize various defaults. Otherwise, the snapshot config will be applied.

Configuration parameters

ai.cpu.enabled: Whether or not the CPU monitoring algorithm is enabled. See Developer Guide. Default value: false
ai.cpu.global: Whether or not the CPU monitoring algorithm should consider usage of the entire machine (true), or just from the Aeonics process (false). Default value: true
ai.cpu.target: The target CPU utilization ratio. Default value: 95
ai.ram.enabled: Whether or not the RAM monitoring algorithm is enabled. See Developer Guide. Default value: false
ai.ram.spin: Whether or not the RAM monitoring algorithm should use a spin wait (true) or sleep (false) while waiting for available memory. Default value: true
ai.ram.target: The target heap space RAM utilization ratio. Default value: 95
ai.ram.timeout: The maximum time to wait until forcibly approve memory utilization. If <= 0, then the system will deny memory utilization and throw an exception after 10 seconds waiting time. Default value: 10000
monitor.enabled: Whether or not the aeonics.data.ingress.Monitor counters are enabled. Enabling metrics does impact the performance of the system. Default value: false
network.buffer.size: The size of the network direct buffer allocated for every network connection. A higher value uses more memory but may reduces latency. A lower value reduces memory usage but may introduce more latency if too small. Default value: 131072
onspinwait.sleep: The amount of time in milliseconds that the spin wait should sleep. If < 0 spin wait does not sleep. Default value: -1
onspinwait.yield: If onspinwait.sleep is negative, defines whether or not the spin wait should yield the current thread (true) or busy-loop (false). Default value: true
scheduler.timezone: The time zone that the scheduler should use internally (e.g.: 'GMT' or 'Europre/Paris'). If not set, the system time zone is used. Default value:
security.token.storage: The name of the storage to store temporary tokens delivered for authentication. If empty, then tokens are using a standalone encrypted form instead. Default value: Memory
security.token.storage.path: The location of the token storage directory within its storage. Default value: tokens/
snapshot.password: The optional password to encrypt the snapshots. Default value: (no encryption)
tls.certificates: The list of TLS certificated available in the system. The value is a JSON list as follows:
```
{
	"domain.name.com": {
		"crt": "base64_pem",
		"key": "base64_pem"
	}
}
```
Default value: {}

tls.ciphers: The list of coma-separated TLS protocol ciphers that the system is allowed to use. Default value:

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,
TLS_AES_256_GCM_SHA384,
TLS_AES_128_GCM_SHA256,
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

tls.protocols: The list of coma-separated TLS protocol variants that the system is allowed to use. Default value: TLSv1.2

Registered items

aeonics.security.Provider

aeonics.security.provider.None (Allow all) Allows every action and authenticates as the Anonymous user.
```
{
}
```
aeonics.security.provider.Builtin (Built-in Identity Provider) Default identity provider that authenticates users based on a cryptographically secure hashed password.
```
{
}
```

aeonics.security.Role

aeonics.security.Role (Role) Security user role. A role is just a tag name associated to a user. It can target a group, a role or any other purpose.
```
{
    "name": "The name of the role.",
}
```

aeonics.security.Constraint

aeonics.security.Constraint (Constraint) Dynamic context security constraint that checks properties of the incoming messages. If the target property does not exist in the message, this constraint fails.
```
{
    "field": "The name of the message field to compare. The dot notation can be used to target subfields (e.g.: metadata.path).",
    "rule": "The pattern matching rule.",
}
```

aeonics.security.Policy

aeonics.security.policy.Allow (Allow) Security policy that verifies if a user is explicitly allowed. It will always return false for the deny check (the user is not denied).

{
    "role": "The pattern matcher for the user roles.",
    "topic": "The pattern matcher for the topic name.",
    "constraints": "A JSON list of constraint IDs to apply.",
    "combination": "How should multiple constraints be combined: (0) AND, (1) OR, (2) XOR, (3) NAND, (4) NOR, (5) XNOR.",
}

aeonics.security.policy.Deny (Deny) Security policy that verifies if a user is explicitly denied. It will always return false for the allow check (the user is not allowed).

{
    "role": "The pattern matcher for the user roles.",
    "topic": "The pattern matcher for the topic name.",
    "constraints": "A JSON list of constraint IDs to apply.",
    "combination": "How should multiple constraints be combined: (0) AND, (1) OR, (2) XOR, (3) NAND, (4) NOR, (5) XNOR.",
}

aeonics.security.User

aeonics.security.User (User) Generic platform User.

{
    "origin": "The ID of the security provider to which this user belongs.",
    "password": "The user password hash. Caution, when creating the user, the password is the hashed value. Update with a new clear text value to force a hash of the password.",
    "active": "true or false.",
    "roles": "A JSON list of roles ID assigned to this user.",
}

aeonics.data.Topic

aeonics.data.Topic (Topic) Serves as the convergence point and distribution of data accross the system.

{
    "subscriptions": "A JSON list containing all the subscriptions. Each subscription is a JSON object with the following properties:
    	'queue' (the ID of the queue), 
		'binding' (the subscription pattern)."
}

aeonics.data.Queue

aeonics.data.queue.MemoryQueue (Volatile) Volatile stored queue. All messages are kept in memory and processed directly.

{
    "parallel": "The maximum number of parallel message processing by this queue.",
    "maxRetry": "The maximum number of times a message can be (re)processed in case of failure.",
    "egress": "The JSON list of egress handler IDs bound to this queue.",
    "regress": "The ordered JSON list of regress handler IDs bound to this queue.",
    "capacity": "The maximum number of pending messages. Once reached, the 'policy' will be applied. -1 if not set.",
    "memory": "The maximum estimated total memory footprint of pending messages. -1 if not set.",
    "policy": "The policy to apply when this queue is full: 
		(0) discard incoming messages, 
		(1) remove the oldest message to make room for the new incoming message, 
		(2) remove the newest message to make room for the new incoming message, 
		(3) block and wait until the message can be accepted. 
		Default value: 0."
}

aeonics.data.queue.StoredQueue (Persistent) Persistent stored queue. All messages are stored to the specified storage and then processed. Storing messages impacts the performance.

{
    "parallel": "The maximum number of parallel message processing by this queue.",
    "maxRetry": "The maximum number of times a message can be (re)processed in case of failure.",
    "egress": "The JSON list of egress handler IDs bound to this queue.",
    "regress": "The ordered JSON list of regress handler IDs bound to this queue.",
    "store": "The ID of the target storage.",
    "last": "The incremental number of the latest message.",
    "current": "The incremental number of the current message being processed."
}

aeonics.data.Message

aeonics.data.Message (Message) Standard platform message with content and metadata.

{
    "content": "The content of the message. A plain string, JSON object or list can be used.",
    "metadata": "The metadata of the message. A JSON object containing all metadata. The 'path' property is essential."
}

aeonics.data.Egress

aeonics.data.egress.Aeonics (Aeonics) Forward messages to another Aeonics system.

{
    "topic": "The name of the topic on the remote Aeonics system.",
    "url": "The url or hostname of the remote Aeonics system."
}

aeonics.data.egress.Client (Origin) Forward messages back to where they came from. This is useful in case of connections where the client expects a response.
```
{
}
```
aeonics.data.egress.Connection (Network connection) Forward messages to an existing network connection.
```
{
    "id": "The internal id of the connection"
}
```

aeonics.data.egress.Console (Console) Forward messages to the standard output of the Aeonics process.

{
    "format": "The plain text template string to send. The format can use the {{content.property}} notation to include properties from the message."
}

aeonics.data.egress.DataSourceQuery (Data source query) Performs a query against the specified datasource.

{
    "datasource": "The name or id of the target data source.",
    "sql": "The SQL request to perform against the data source. The {{content.property}} notation can be used to substitute message parameters."
}

aeonics.data.egress.Debug (Debug) Sends the message to the debugger.
```
{
    "tag": "The debugger filter tag."
}
```

aeonics.data.egress.File (File) Forward messages to a file on the local filesystem.

{
    "file": "The path and name of the target file.",
    "format": "The plain text string to write in the file. The {{content.property}} notation can be used to substitute message parameters."
}

aeonics.data.egress.Foreach (Splitter) Splits a message property into multiple messages.

{
    "topic": "The name of the topic in which to send all duplicated messages.",
    "list": "The name of the message property that contains a list of elements.",
    "key": "The message routing key. To use the original message routing key, use {{metadata.path}}.",
    "content": "The content of the newly created message. Use {{content}} to preserve the splitted value."
}

aeonics.data.egress.Http (HTTP endpoint) Forward messages to a remote HTTP endpoint.

{
    "headers": "A JSON object containing the headers name and value. Both the header name and the value can use the {{content.property}} notation to substitute message parameters.",
    "method": "The name of the HTTP method to use (GET, POST,...).",
    "body": "The plain text request body to send. The request body should be properly encoded according to the Content-Type header. The {{content.property}} notation can be used to substitute message parameters.",
    "url": "The url of the remote endpoint. It should start with http:// or https://."
}

aeonics.data.egress.Log (Logger) Log a message.

{
    "level": "The log level. (Info: 800, Warning: 900, Severe: 1000)",
    "format": "The plain text template string to send. The format can use the {{content.property}} notation to include properties from the message.",
    "tag": "The log entry tag. The tag can use the {{content.property}} notation to include properties from the message."
}

aeonics.data.egress.Sendmail (Email) Sends an email using the Unix sendmail utility ("/usr/sbin/sendmail -t -i"). This element only works on compatible systems.

{
    "cc": "The email addresses to cc. This can be any email address separated by a coma ',' or left blank. The {{content.property}} notation can be used to substitute message parameters.",
    "bcc": "The email addresses to bcc. This can be any email address separated by a coma ',' or left blank. The {{content.property}} notation can be used to substitute message parameters.",
    "bodyText": "The plain text version of the email. The {{content.property}} notation can be used to substitute message parameters.",
    "subject": "The email subject. The {{content.property}} notation can be used to substitute message parameters.",
    "replyTo": "The email address to reply to. This can be any email address or left blank. The {{content.property}} notation can be used to substitute message parameters.",
    "from": "The sender of the email. This should be an authorized sender for this system. The {{content.property}} notation can be used to substitute message parameters.",
    "bodyHtml": "The html version of the email (or left blank). The {{content.property}} notation can be used to substitute message parameters.",
    "to": "The email address of the recipient. The {{content.property}} notation can be used to substitute message parameters."
}

aeonics.data.egress.Storage (Storage) Save messages into an existing Storage.

{
    "path": "The target path to use in the storage. The {{content.property}} notation can be used to substitute message parameters.",
    "format": "The plain text string to write in the storage. The {{content.property}} notation can be used to substitute message parameters.",
    "storage": "The name or id of the target storage."
}

aeonics.data.egress.TCP (TCP connection) Forward messages to a TCP remote endpoint.

{
    "port": "The port number of the remote endpoint.",
    "payload": "The plain text string to send. The {{content.property}} notation can be used to substitute message parameters.",
    "host": "The host name or IP of the remote endpoint.",
    "secure": "Boolean value to use a secure TLS connection."
}

aeonics.data.egress.Topic (Topic) Forward a message into another topic channel.

{
    "topic": "The name of the topic in which to send messages.",
    "key": "The message routing key. To use the original message routing key, use {{metadata.path}}.",
    "content": "The content of the message to send. Use {{content}} to preserve the original value."
}

aeonics.data.egress.UDP (UDP connection) Forward messages to a UDP remote endpoint.

{
    "port": "The port number of the remote endpoint.",
    "payload": "The plain text string to send. The {{content.property}} notation can be used to substitute message parameters.",
    "host": "The host name or IP of the remote endpoint."
}

aeonics.data.egress.Void (Nothing) Does nothing.
```
{
}
```

aeonics.data.Ingress

aeonics.data.ingress.DataSourceQuery (Scheduled data source query) Performs a query against the specified datasource and emits the result as a message.

{
    "ical": "The recurence of the task in ICAL format (RRULE). Leave blank to run just once immediately.",
    "datasource": "The name or id of the target data source.",
    "topic": "The name of the topic in which to publish messages.",
    "tag": "The message tag to use.",
    "sql": "The SQL request to perform against the data source."
}

aeonics.data.ingress.Debugger (Debugger) Receives debug messages and publishes them in the specified topic. There can be only one instance of Debugger.
```
{
    "topic": "The name of the topic in which to publish messages."
}
```
aeonics.data.ingress.Discard (Discard) Receives discarded messages and publishes them as last resort in the specified topic. There can be only one instance of Discard.
```
{
    "topic": "The name of the topic in which to publish messages."
}
```

aeonics.data.ingress.HttpRequest (Scheduled HTTP request) Fetches content from a remote HTTP endpoint at regular interval.

{
    "headers": "A JSON key/value pair object containing additional request headers. Set to '{}' if no additional headers are specified.",
    "ical": "The recurence of the task in ICAL format (RRULE). Leave blank to run just once immediately.",
    "method": "The HTTP method to use (GET, POST,...). ",
    "topic": "The name of the topic in which to publish messages.",
    "tag": "The message tag to use.",
    "body": "The raw body content to send with the request.",
    "url": "The URL to fetch."
}

aeonics.data.ingress.Logger (Logger) Receives log messages and publishes them in the specified topic. There can be only one instance of Logger.
```
{
    "topic": "The name of the topic in which to publish messages."
}
```

aeonics.data.ingress.Monitor (Monitor) Receives metrics and monitoring information and publish them at regulat interval in the specified topic. There can be only one instance of Monitor.

{
    "topic": "The name of the topic in which to publish messages.",
	"ical": "The recurence of the publication of the metrics in ICAL format (RRULE). Leave blank to run just once immediately."
}

aeonics.data.ingress.Nothing (Nothing) Does nothing.

{
    "topic": "The name of the topic to attach to but never publish any message."
}

aeonics.data.ingress.Publish (Scheduled Message) Emits a static message at regular interval.

{
    "ical": "The recurence of the task in ICAL format (RRULE). Leave blank to run just once immediately.",
    "topic": "The name of the topic in which to publish messages.",
    "tag": "The message tag to use.",
    "content": "The content of the message. It can be plain text or a JSON object."
}

aeonics.data.ingress.UDP (UDP Server) Receive messages from a UDP stream. The UDP packets are not decoded and sent as-is into the target topic.

{
    "address": "The local binding address. Use '0.0.0.0' to bind all IPv4 interfaces, and '::' to bind all IPv4 and IPv6 interfaces.",
    "port": "The port number to listen.",
    "topic": "The name of the topic in which to publish messages."
}

aeonics.data.Regress

aeonics.data.regress.AddProperty (Add property) Add a property to the message.

{
    "value": "The value of the property. The {{content.property}} notation can be used to substitute message parameters.",
    "key": "The name of the property. The {{content.property}} notation can be used to substitute message parameters."
}

aeonics.data.regress.Base64Decode (Decode Base64) Decodes a message property in Base64 encoding. The target property is substituted with its decoded binary string representation.
```
{
    "key": "The name of the property to decode."
}
```
aeonics.data.regress.Base64Encode (Encode Base64) Encodes a message property in Base64 encoding. The target property is substituted with its encoded string representation.
```
{
    "key": "The name of the property to encode. If the property contained structured data, its JSON form is encoded instead."
}
```
aeonics.data.regress.CSVDecode (Decode CSV) Decodes a message property in CSV. The first line of the CSV data is expected to contain the column names. The target property is substituted with its decoded list of entries.
```
{
    "key": "The name of the property to decode."
}
```

aeonics.data.regress.CopyProperty (Copy property) Duplicates a message property.

{
    "from": "The name of the source property to copy. The {{content.property}} notation can be used to substitute message parameters.",
    "to": "The name of the target property. The {{content.property}} notation can be used to substitute message parameters."
}

aeonics.data.regress.DataSourceQuery (Data source query) Performs a query against the specified datasource and stores the result in the message.

{
    "datasource": "The name or id of the target data source.",
    "key": "The name of the message property in which to store the query result.",
    "sql": "The SQL request to perform against the data source. The {{content.property}} notation can be used to substitute message parameters."
}

aeonics.data.regress.Debug (Debug) Sends the message to the debugger.
```
{
    "tag": "The debugger filter tag."
}
```
aeonics.data.regress.Delay (Delay) Add a delay to the message to make sure that a minimum of time has elapsed before the next processing step. The delay is enforced from the message creation date, not from when the delay is set.
```
{
    "delay": "The delay duration in milliseconds."
}
```
aeonics.data.regress.Duplicate (Duplicate message) Copies the message in the target topic.
```
{
    "topic": "The name of the topic in which to send a copy of the message."
}
```
aeonics.data.regress.Expire (Timeout) Add a timeout to the message such that it will be dropped if the timeout has elapsed. The timeout is enforced from the message creation date, not from when it is set.
```
{
    "timeout": "The timeout duration in milliseconds."
}
```

aeonics.data.regress.Filter (Filter) Filters or retains messages based on the specified condition.

{
    "drop": "If true, the filter will discard the matching messages. If false, the filter will only allow the matching messages to proceed.",
    "value": "The value of the filter. Multiple possible values can be specified using a JSON array.",
    "key": "The name of the property. The {{content.property}} notation can be used to substitute message parameters.",
    "operator": "The check to perform. One of == (equals), != (is different), < (smaller than), > (greater than), <= (smaller or equal), >= (greater or equal)."
}

aeonics.data.regress.HexDecode (Decode Hexadecimal) Decodes a message property in hexadecimal encoded pairs. The target property is substituted with its decoded binary string representation.
```
{
    "key": "The name of the property to decode."
}
```
aeonics.data.regress.HexEncode (Encode Hexadecimal) Encodes a message property in hexadecimal encoded pairs. The target property is substituted with its encoded string representation.
```
{
    "key": "The name of the property to encode. If the property contained structured data, its JSON form is encoded instead."
}
```

aeonics.data.regress.HttpFetch (HTTP request) Fetches content from a remote HTTP endpoint and store it in the message.

{
    "headers": "A JSON key/value pair object containing additional request headers. Set to {} if no additional headers are specified. The {{content.property}} notation can be used to substitute message parameters.",
    "method": "The HTTP method to use (GET, POST,...). The {{content.property}} notation can be used to substitute message parameters.",
    "body": "The raw body content to send with the request. The {{content.property}} notation can be used to substitute message parameters.",
    "key": "The property of the message in which to store the HTTP response. The {{content.property}} notation can be used to substitute message parameters. If left empty, the message will be overwritten with the HTTP response.",
    "url": "The URL to fetch. The {{content.property}} notation can be used to substitute message parameters."
}

aeonics.data.regress.JsonDecode (Decode JSON) Decodes a message property in JSON encoding. The target property is substituted with its decoded representation.
```
{
    "key": "The name of the property to decode."
}
```
aeonics.data.regress.JsonEncode (Encode JSON) Encodes a message property in JSON encoding. The target property is substituted with its encoded string representation.
```
{
    "key": "The name of the property to encode."
}
```
aeonics.data.regress.MakeList (Add list property) Adds an empty list property. If the property already exists, its value is copied as the first element of the list.
```
{
    "key": "The name of the property."
}
```
aeonics.data.regress.MakeObject (Add object property) Adds an empty key/value pair object property. If the property already exists, its value is copied with the "default" key.
```
{
    "key": "The name of the property."
}
```
aeonics.data.regress.Noop (Nothing) Does nothing.
```
{
}
```
aeonics.data.regress.Overwrite (Overwrite message) Completely rewrites the message content using the specified value. If the value is a JSON object representation (starting with "{") then it is converted to structured data automatically.
```
{
    "content": "The new message content. The {{content.property}} notation can be used to substitute message parameters."
}
```

aeonics.data.regress.RemoveProperty (Remove property) Removes a property from the message.

{
    "key": "The name of the property to remove. The {{content.property}} notation can be used to substitute message parameters."
}

aeonics.data.regress.TimeFilter (Time filter) Filters the message based on temporal criteria. All defined criteria must match for the filter to match a message. Example, if year 2000 and month 7 are set, the filter will match all messages in July 2000 but none in any other month or year.

{
    "drop": "If true, the filter will discard the matching messages. If false, the filter will only allow the matching messages to proceed.",
    "hours": "The hour (0-23) to match. Multiple values can be specified using a JSON list. Leave blank to not match this value.",
    "seconds": "The second (0-59) to match. Multiple values can be specified using a JSON list. Leave blank to not match this value.",
    "months": "The month number (1-12) to match. Multiple values can be specified using a JSON list. Leave blank to not match this value.",
    "weeks": "The week number (1-53) match. Multiple values can be specified using a JSON list. Leave blank to not match this value.",
    "daysofweek": "The day of the week (1 = Monday, 7 = Sunday) to match. Multiple values can be specified using a JSON list. Leave blank to not match this value.",
    "timezone": "The name of the timezone of the filter. Example: 'GMT' or 'Europre/Paris'.",
    "minutes": "The minute (0-59) to match. Multiple values can be specified using a JSON list. Leave blank to not match this value.",
    "days": "The days (1-31) to match. Multiple values can be specified using a JSON list. Leave blank to not match this value.",
    "key": "The name of the property containing the time. If the property does not exist or is empty, the current time is used instead.",
    "years": "The year to match. Multiple values can be specified using a JSON list. Leave blank to not match this value."
}

aeonics.data.regress.Timestamp (Timestamp) Converts an ISO-8601 time property to a unix timestamp. If the property is empty or does not exist, the current timestamp is set. If the property already contained a timestamp, it is preserved.
```
{
    "seconds": "If true, the timestamp will be in seconds. If false, the timestamp will be in milliseconds.",
    "key": "The name of the property. The {{content.property}} notation can be used to substitute message parameters."
}
```
aeonics.data.regress.URLDecoder (Decode URL) Decodes a message property in URL encoding. The target property is substituted with its decoded binary string representation.
```
{
    "key": "The name of the property to decode."
}
```
aeonics.data.regress.URLEncoder (Encode URL) Encodes a message property in URL encoding. The target property is substituted with its encoded string representation.
```
{
    "key": "The name of the property to encode. If the property contained structured data, its JSON form is encoded instead."
}
```
aeonics.dynamic.data.DynamicRegress (Java Serverless) Executes the provided Java code. This processor should ideally be declared using the Serverless manager to ensure proper deployment.
```
{
    "code": "The code must be a class that implements the Supplier interface."
}
```

aeonics.rest.Router (HTTP Router) Routes the HTTP request to the proper endpoint.

{
    "path": "A wildcard filter to restrict the delivered URLs.",
    "host": "A wildcard filter to match the requested host. Use this parameter to apply virtual host routing."
}

aeonics.rest.regress.HttpBodyDecoder (Decode HTTP form data) Decodes a message property in either multipart/form-data or application/x-www-form-urlencoded encoding. The target property is substituted with its decoded binary string representation.
```
{
    "key": "The name of the property to decode."
}
```

aeonics.storage.Storage

aeonics.storage.MemoryStorage (Memory) In-memory storage. The content of this storage is not preserved upon restart.
```
{
}
```
aeonics.storage.DiskStorage (Disk) Local disk storage.
```
{
	"root": "The path to the root folder."
}
```
aeonics.storage.DataSourceStorage (Datasource) Use an existing datasource as storage. The datasource tables and columns are cached in memory when creating or updating this item, so changes in the underlying datasource will not be visible. To refresh this storage, update it with the same values.
```
{
	"source": "The ID of the existing datasource item.",
	"schema": "The name of the schema (database) to expose."
}
```

aeonics.sql.DataSource

aeonics.sql.DataSource (Datasource) Maintains a connection to a database.

{
	"size": "The maximum number of connections in parallel.",
	"driver": "The name of the JDBC driver class. (e.g.: org.mariadb.jdbc.Driver).",
	"connection": "The JDBC connection string. (e.g.: jdbc:mariadb://localhost:3306/db?username=user&password=pass)."
}

aeonics.ui.Comment

aeonics.ui.Comment (Comment) Free text comment related to an item. No check is performed for the existence of the referenced item and no cleanup is performed upon removal of the item from the registry.

{
	"text": "The free text of the comment.",
	"item": "The ID of the related item.",
	"type": "The registry type of the target item.",
	"author": "The name of the author of the comment (free text).",
	"edited": "The modification timestamp.",
	"flags": "Custom flags as an integer. There is no predefined meaning for those flags."
}

aeonics.ui.Group

aeonics.ui.Group (Group) Forms a logical group of items of a certain type without further meaning. If this group is removed from the registry, all its items are also removed from the registry.
```
{
	"type": "The registry type of grouped items.",
	"items": "A JSON list of item IDs."
}
```

Dynamic

Description

{
	"name": "dynamic"
	"dependency": ["core", "http"]
	"shared": false
}

This module allows to deploy REST endpoints, ingress, regress and egress functions directly from the raw Java source code instead of deploying a compiled module. There is no integrity check performed on the deployed code, so beware of security and performance implications.

Configuration parameters

rest.dynamic.allow.override: Whether or not dynamic REST endpoints can override other internal endpoints. Default value: false
rest.dynamic.path: The path on the server to automatically load .java files to deploy dynamic REST endpoints. Default value: rest
rest.openapi.allow.override: Whether or not openapi REST endpoints can override other internal endpoints. Default value: false
rest.openapi.path: The path on the server to automatically load .json files to deploy openapi REST endpoints. Default value: rest

Registered items

aeonics.data.Egress

aeonics.dynamic.data.DynamicEgress (Java Serverless) Executes the provided Java code. This forwarder should ideally be declared using the Serverless manager to ensure proper deployment.
```
{
	"code": "The code must be a class that implements the Supplier<Egress> interface."
}
```

aeonics.data.Ingress

aeonics.dynamic.data.DynamicIngress (Java Serverless) Executes the provided Java code as a background process to collect messages. This data collector should ideally be declared using the Serverless manager to ensure proper deployment.
```
{
	"code": "The code must be a class that implements the Supplier<Ingress> interface. BasicIngress is supported.",
	"topic": "The name of the topic in which to publish messages."
}
```

aeonics.data.Regress

aeonics.dynamic.data.DynamicRegress (Java Serverless) Executes the provided Java code. This processor should ideally be declared using the Serverless manager to ensure proper deployment.
```
{
	"code": "The code must be a class that implements the Supplier<Regress> interface."
}
```

aeonics.dynamic.data.regress.Javascript (Javascript) Executes the provided Javascript code. This processor requires a polyglot server environment.

{
    "code": "The code must be a function called 'process' that accepts two input parameters: the message content, and the message metadata. The signature is thus 'function process(content, metadata) { ... }'."
}

aeonics.rest.Endpoint

aeonics.dynamic.rest.DynamicEndpoint (Java Serverless) Executes the provided Java code. This item should ideally be declared using the Serverless manager to ensure proper deployment.
```
{
	"code": "The code must be a class that implements the Supplier<Endpoint> interface."
}
```
aeonics.dynamic.rest.OpenAPIEndpoint (OpenAPI) Executes the provided Java code. This item should be created using the REST API by uploading an OpenAPI JSON specification..
```
{
	"code": "The code must be a class that extends the RestEndpoint class."
}
```

aeonics.util.Item

aeonics.dynamic.DynamicItem (Java Serverless Item) Creates an Item in the Registry using the provided Java code.

{
	"code": "The code must be a class that implements the Supplier<Item> interface.",
	"registry": "The name of the Registry in which to register the generated item. Default: 'Void'."
}

Http

Description

{
	"name": "http"
	"dependency": ["core"]
	"shared": true
}

This module provides an HTTP(S) 1.1 asynchronous web server, Websocket server, REST API fundamentals and other HTTP-related operations. Caution, some operations are disallowed (e.g.: chunked encoding).

By default, an HTTP server ingress is started and listens on port 80. If a snapshot is loaded, the snapshot configuration is used instead.

The following HTTP request and response filters are also registered:

HttpsFilter: If the http.forcehttps config parameter is set and the connection is not secure, it will send a 308 redirect to the same URL using HTTPS. It will also set the Strict-Transport-Security response header.
OptionsMethodFilter: If the request method is OPTIONS, it will respond directly with a 204 code and an empty content.
CorsFilter: It will set the CORS response headers defined in the config on every HTTP response.
HeadMethodFilter: If the request method is HEAD, it will respond directly with a 200 code and an empty content.
GzipFilter: It will compress some eligible HTTP response. All image, audio or video content will never be compressed because we consider that the best compression is already used and re-compressing it would only make it worse. Compression is used only when the Accept-Encoding request header contains gzip and the content length is greater than 150 bytes. Compressing smaller data would actually make it larger because of the compression metadata.

Configuration parameters

http.auth.basic.enabled: Whether or not the HTTP Basic authentication is enabled as an alternative to Bearer token. Default value: true
http.cors.access-control-allow-credentials: The value to use for the matching CORS header. If blank, the header is not set. Default value: true
http.cors.access-control-allow-headers: The value to use for the matching CORS header. If blank, the header is not set. Default value: Authorization,Content-Length,Content-Type,Accept,Accept-Language,Accept-Encoding
http.cors.access-control-allow-methods: The value to use for the matching CORS header. If blank, the header is not set. Default value: GET,POST,PUT,DELETE,OPTIONS
http.cors.access-control-allow-origin: The value to use for the matching CORS header. If blank, the header is not set. Default value: *
http.default.port: The port to use for the default HTTP server when no snapshot exists. Default value: 80
http.default.address: The address to use for the default HTTP server when no snapshot exists. Default value: 0.0.0.0
http.forcehttps: Whether or not to force a redirect to HTTPS when using regular HTTP. Note that there must be a HTTPS ingress deployed for this redirection to succeed. Default value: false
http.header.client_ip: The name of the http request header that contains the client ip address (in case a proxy is placed in front).
http.headers: A list of key/value pair in JSON format of response headers to set for every HTTP response. Default value: {}
http.maxbodysize: The maximum supported http request body size. Default value: 5242880
http.maxheadersize: The maximum length of http request headers. Default value: 4096
http.maxurisize: The maximum length of the http request URI. Default value: 500
http.timeout: The idle time in milliseconds allowed for http connections. Connections exceeding the idle timeout will be closed. Default value: 120000
rest.enabled: Whether or not to enable the REST API. Default value: true
rest.rooturi: The URL prefix for all REST API endpoints. Default value: /api
websocket.maxbodysize: The maximum length of the websocket payload. Default value: 5242880
websocket.maxchunksize: The maximum length of websocket chunks. Packets exceeding this size will be split in multiple chunks. Default value: 524288

Registered items

aeonics.data.Egress

aeonics.rest.egress.HttpResponse (HTTP Response) Generates a valid HTTP response and sends it to the origin of the message.

{
	"status": "The response status code. Example: 200.",
	"mime": "The response mime type. Example: 'application/json'. This parameter can use the {{content.property}} notation to substitute message parameters.",
	"body": "The plain text response body to send. This parameter can use the {{content.property}} notation to substitute message parameters."
}

aeonics.data.Ingress

aeonics.server.http.HttpServer (HTTP Server) Standard HTTP 1.1 server. This server does not support chunked encoding.

{
	"topic": "The name of the topic in which to publish incoming requests.",
	"address": "The local binding address. Use '0.0.0.0' to bind all IPv4 interfaces, and '::' to bind all IPv4 and IPv6 interfaces.",
	"port": "The port number to listen. The standard http port is 80 and 443 for https.",
	"certificate": "The path to the PEM encoded certificate to secure the connection. Leave blank to use unsecure connections.",
	"privateKey": "The path to the PEM encoded private key file to secure the connection. Leave blank to use unsecure connections."
}

aeonics.server.http.WebsocketServer (Websocket Server) Websocket server. This element is tied to the HTTP server. There can be only one Websocket server on the system.
```
{
	"topic": "The name of the topic in which to publish incoming messages."
}
```

aeonics.server.websocket.WebSocketIngress (Websocket Endpoint) Connects to a remote Websocket endpoint and publishes all incoming messages.

{
	"topic": "The name of the topic in which to publish incoming requests.",
	"url": "The URL to connect to. This must be a websocket endpoint starting with either 'ws(s)://' or 'http(s)://'.",
	"headers": "A JSON key/value pair object containing additional request headers. Set to {} if no additional headers are specified."
}

aeonics.data.Regress

aeonics.rest.regress.HttpBodyDecoder (Decode HTTP form data) Decodes a message property in either multipart/form-data or application/x-www-form-urlencoded encoding. The target property is substituted with its decoded binary string representation.
```
{
	"key": "The name of the property to decode."
}
```
aeonics.rest.Router (HTTP Router) Routes the HTTP request to the proper endpoint.
```
{
	"host": "A wildcard filter to match the requested host. Use this parameter to apply virtual host routing. Default: '#'",
	"path": "A wildcard filter to restrict the delivered URLs. Default: '#'"
}
```
Note: The router will (1) apply all aeonics.rest.filter.Filter registered in the registry for an initial request filtering, (2) then find and execute the proper aeonics.rest.Endpoint registered in the registry, (3) then apply all aeonics.rest.filter.Filter registered in the registry for a final response filtering. If an error happens during the process, it will be automatically converted to an HTTP 500 error. If the error is a aeonics.rest.RestException, the description will be sent as JSON content and the error stack trace will be included if the log.level is equal or lower than FINE (500).

aeonics.rest.filter.Filter

aeonics.rest.filter.CorsFilter (CORS) Adds the CORS headers to every HTTP response based on the globally configured values (http.cors.*).
```
{
}
```
aeonics.rest.filter.GzipFilter (GZip) Compresses the HTTP response if the client supports it. Media content (images, music, video) are not compressed because it is not worth it.
```
{
}
```
aeonics.rest.filter.HeadersFilter (Headers) Sets additional HTTP response headers depending on the global config 'http.headers'.
```
{
}
```
aeonics.rest.filter.HeadMethodFilter (HEAD method) Returns an empty content for the HEAD request method.
```
{
}
```
aeonics.rest.filter.HttpsFilter (Force HTTPS) Forces a redirect to the same page in HTTPS with HSTS header. The redirection happens only if the 'http.forcehttps' global configuration is set.
```
{
}
```
aeonics.rest.filter.OptionsMethodFilter (OPTIONS method) Returns an empty content for the OPTIONS request method.
```
{
}
```

Mqtt

Description

{
	"name": "mqtt"
	"dependency": ["core"]
	"shared": false
}

This module provides an MQTT(S) 4 server. QoS 0, 1 and 2 are supported but since the underlying processing logic is based on processing pipelines, the messages are acknowledged directly.

By default, an MQTT server ingress is started and listens on port 1883. If a snapshot is loaded, the snapshot configuration is used instead.

Configuration parameters

mqtt.maxpayloadsize: The maximum length of the message payload. Default value: 5242880
mqtt.timeout: The idle time in milliseconds allowed for mqtt connections. Connections exceeding the idle timeout will be closed. Default value: 300000

Registered items

aeonics.data.Egress

aeonics.client.mqtt.MqttPublish (MQTT) Publish messages to an MQTT endpoint.

{
	"topic": "The name of the destination topic. The {{content.property}} notation can be used to substitute message parameters.",
	"url": "The full URL to connect to the remote endpoint. Example: 'mqtt://username:password@host:port'.",
	"qos": "The desired QoS (0 or 1).",
	"clientId": "The client identifier to use in the connection.",
	"payload": "The plain text string payload to publish. The {{content.property}} notation can be used to substitute message parameters."
}

aeonics.data.Ingress

aeonics.client.mqtt.MqttSubscription (MQTT Subscription) Receive messages from a remote MQTT endpoint.

{
	"topic": "the name of the Aeonics topic in which to publish received messages.",
	"url": "The full URL to connect to the remote endpoint. Example: 'mqtt://username:password@host:port/topic'.",
	"qos": "The desired QoS (0 or 1).",
	"clientId": "The client identifier to use in the connection."
}

aeonics.server.mqtt.MqttServer (MQTT Server) Standard MQTT 4 server.

{
	"topic": "The name of the topic in which to publish incoming messages.",
	"address": "The local binding address. Use '0.0.0.0' to bind all IPv4 interfaces, and '::' to bind all IPv4 and IPv6 interfaces.",
	"port": "The port number to listen. The standard mqtt port is 1883 and 8883 for mqtts.",
	"certificate": "The path to the PEM encoded certificate to secure the connection. Leave blank to use unsecure connections.",
	"privateKey": "The path to the PEM encoded private key file to secure the connection. Leave blank to use unsecure connections."
}

Rest admin

Description

{
	"name": "rest-admin"
	"dependency": ["http"]
	"shared": false
}

This module provides all the administrative REST APIs to manage the system, as well as serve basic filesystem assets. This module is required to use the web management interface.

This module registers the following http filters in the registry:

FailedLoginFilter: It will monitor the Authorization request header and the /api/security/login endpoint. If too many failed attempts are performed within a certain time period, the origin IP address will be banned for some time. It is very important to understand the implications of a reverse-proxy in this case because all requests could be identified as the proxy and thus can block all communications. See http.header.client_ip.
ResponseTimeFilter: It will insert the x-ae-response-time response header that measures the request processing time in nanoseconds.

Configuration parameters

http.cache-max-age: The value of the Cache-Control max age http response header to use when delivering static assets. If = 0, the no-cache is used. If < 0, then no Cache-Control header is sent. Default value: 86400
http.default404: The path to the default not-found error page to deliver for 404 errors matching a requests with a text/html Accept request header. Default value: index.html
http.default400: The path to the default client-side error page to deliver for all 4xx errors matching a requests with a text/html Accept request header. Default value: index.html
http.default500: The path to the default server-side error page to deliver for all 5xx errors matching a requests with a text/html Accept request header. Default value: index.html
http.defaultextension: The file extension that can be omitted from the URL (e.g.: "/foo" would match "/foo.html"). Default value: .html
http.defaultindex: The file name of the default page to send when requesting a directory URL (e.g.: "/doc/" would match "/doc/index.html"). Default value: index.html
http.enable.publish: Whether or not to enable the "/api/publish" endpoint to publish arbitraty messages on any topic. Default value: true
http.enable.webapps: Whether or not to enable static content to be delivered by the http server. Default value: true
http.webapppath: The directory on the server to use as the root for static assets. Default value: www

Registered items

aeonics.rest.filter.Filter

aeonics.filters.FailedLoginFilter (Failed Login Ban) Bans the IP address of the client for a given time if too many failed authentication happen.
```
{
}
```
aeonics.filters.ResponseTimeFilter (Response Time) Adds the 'x-ae-response-time' response header with the request execution time in nanoseconds.
```
{
}
```

Security

Description

{
	"name": "security"
	"dependency": ["core", "http"]
	"shared": false
}

This module provides additional security providers such as SAML or OIDC. It also enables the system to act as a OAuth2 server endpoint to acquire user credentials and enables use of Multifactor Authentication (MFA) using time-based one-time passwords (TOTP).

The purpose of the OAuth2 authentication is to allow third parties to request final user tokens and act on their behalf. It is therefore important that allowed third parties be trusted and registered in the system. The OAuth2 authentication includes three types of components:

Dedicated REST API endpoints
Dedicated login web interface
Registered OAuth Clients

Once an authentication flow is started, it has 5 minutes to complete. Refresh tokens are issued for a maximum of 30 days. All intermediate authorization tokens, user tokens and refresh tokens are cleared upon restart of the system unless they are stored on a persistent storage.

The purpose of the SAML and OIDC authentication is to allow third parties to authenticate the user and provide SSO capabilities. The SAML and OIDC authentication includes two types of components:

Dedicated REST API endpoints
Security Providers

Once an authentication flow is started, it has 5 minutes to complete. All intermediate states are cleared upon restart of the system unless they are stored on a persistent storage.

When using multiple Aeonics instances (typically in case of load balancing or fail over), you should use a shared or synchronized storage to store tokens, temporary states and refresh tokens.

Configuration parameters

oauth.token.expires_in: The default authorization token lease time in seconds
oauth.authorize.code.enabled: Whether or not the Authorization Code Grant is enabled.
oauth.authorize.token.enabled: Whether or not the Implicit Grant is enabled.
oauth.token.authorization_code.enabled: Whether or not the Access Token Request is enabled.
oauth.token.password.enabled: Whether or not the Resource Owner Password Credentials Grant is enabled.
oauth.token.client_credentials.enabled: Whether or not the Client Credentials Grant is enabled.
oauth.token.refresh_token.enabled: Whether or not the Refreshing an Access Token is enabled.
security.code.storage: The name of the storage to store temporary states required for authentication. If empty, a local internal variable in used instead. Default value: Memory
security.code.storage.path: The location of the state storage directory within its storage. Default value: code/
security.refresh.storage: The name of the storage to store OAuth2 refresh tokens. If empty, a local internal variable in used instead. Default value: Memory
security.refresh.storage.path: The location of the refresh token storage directory within its storage. Default value: refresh/
security.otp.period: The time period in seconds for the TOTP generation. Default value: 30
security.otp.digits: The expected length of the TOTP code. Default value: 6
security.otp.algorithm: The hash algorithm used to generate TOTP. Default value: SHA1
security.otp.issuer: The name of the issuer of the service. This is optional. Default value: Aeonics
security.otp.storage: The name of the storage to store OTP metadata. If empty, a local internal variable in used instead. Default value: Memory
security.otp.storage.path: The location of the OTP metadata storage directory within its storage. Default value: otp/

Registered items

aeonics.security.Provider

aeonics.saml.SamlProvider (SAML Identity Provider) Delegates the authentication to a SAML Identity Provider. Users must be provisionned in the system to match successfully. This provider only supports the HTTP-Redirect request binding with a HTTP-POST response binding. The response from the Identity Provider must be in the form of a 'nameid-format:emailAddress' NameID.
To obtain the SP metadata file, visit the /saml/descriptor?provider=[id] url on your Aeonics instance.
```
{
	"issuer": "The EntityID of this Service Provider.",
	"idp": "The Location of the Identity Provider SingleSignOnService.",
	"callback": "The callback response URL to this Service Provider (AssertionConsumerService). Must be 'https://[host]/saml/response' where the host points to this Service Provider."
}
```

aeonics.oidc.OidcProvider (OIDC Identity Provider) Delegates the authentication to an OIDC Identity Provider. The OIDC Identity Provider must suport the "email" scope. Users must be provisionned in the system to match successfully.
You should register the Aeonics application at the OIDC provider side. The redirect URI should be: https://[host]/oidc/response.

{
	"autorizeUrl": "The full URL to the '/autorize' endpoint.",
	"tokenUrl": "The full URL to the '/token' endpoint.",
	"userInfoUrl": "The full URL to the '/userinfo' endpoint.",
	"redirectUri": "The redirect URI to this instance. Must be 'https://[host]/oidc/response' where the host points to this Client Application.",
	"clientId": "The clientId provided by the OIDC server.",
	"clientSecret": "The clientSecret provided by the OIDC server."
}

aeonics.oauth.OAuthClient

aeonics.oauth.OAuthClient (OAuth2 Client) Authorize a third party to use OAuth2 to obtain user tokens. When requesting a token using the Client Credentials Grant flow, the client will be mapped to an existing user. The Cliend ID is the ID of this item.

{
	"redirectUri": "The redirection URL to send the Authorization Code.",
	"id": "The Client ID that can be used to authenticate (this value will be auto-generated and should not be modified).",
	"clientSecret": "The Client Secret that can be used to authenticate (this value will be auto-generated and should not be modified).",
	"user": "The ID of the User that is bound to this OAuth2 client, if any."
}