You are reading the documentation for an outdated Corteza release. 2023.9 is the latest stable Corteza release.

Corteza Federation

Corteza Federation is currently in experimental mode and the federation function is disabled by default. Set the FEDERATION_ENABLED .env variable to true if you wish to enable it.

Corteza Federation enables different Corteza instances to establish a federated network to freely and securely exchange information.

This document helps you through the process of setting up your federated network and configuring data sharing.

Quick access:

Federated Nodes

A federated node is a Corteza instance (server) with the Federation feature enabled.

A node can expose data to its destination nodes (acts as an origin), or consume shared data from its origin nodes (acts as a destination).

A node can be both the origin and a destination.

Before we can exchange any data between the nodes, they need to go through the node pairing process.

Node pairing

Node pairing flow outline:

  1. the origin node registers a destination node,

  2. the origin node sends an invite to the destination node,

  3. the destination node accepts the invite, either via email or via some other channel,

  4. the origin node accepts the handshake request sent by the destination node.

You can start the node pairing process from any node.
To register a new node:

  1. navigate to the Corteza Admin,

  2. click on the "Nodes" under "Federation" in the navigation drawer,

  3. click on the "new" button,

  4. provide the requested data regarding node we wish to connect with,

  5. press the "Submit" button.

To send the invitation:

  1. navigate to the Corteza Admin,

  2. click on the "Nodes" under "Federation" in the navigation drawer,

  3. click on the node you wish to send an invitation for,

  4. click on the "Generate Federation Link" button and either

    • copy the invitation URL, or

    • insert the contact email of the digital location the invite should be sent to.

The generated invite URL includes a secure OTT token, so make sure to send it over a secure channel.
To accept the email invitation:

  1. click on the "Pair Federation Node" button,

  2. enter the received URL and confirm.

The node pairing does not proceed until the pairing URL is inserted, and the handshake request is accepted by the other party.
To accept the invitation without email:

  1. navigate to the Corteza Admin,

  2. click on the "Nodes" under "Federation" in the navigation drawer,

  3. click on the …​ button, // @todo

  4. enter the received URL and confirm.

The node pairing does not proceed until the pairing URL is inserted, and the handshake request is accepted by the other party.
To accept the node pair handshake request:

  1. navigate to the Corteza Admin,

  2. click on the "Nodes" under "Federation" in the navigation drawer,

  3. click on the node you wish to accept the request for,

  4. click on the warning icon to confirm the request.

This final step is done on the origin server (the one that initiated the handshake).

Data Synchronization

When two nodes have successfully performed the node pairing process, we can share the data between the two nodes.

Shared modules are created by the Federation system and can not be manually removed or updated.

Sharing data

An origin node can share data with it’s paired destination nodes.

An origin node defines what modules a specific destination node is allowed to access.

You can only share data with nodes that have been successfully paired.
To share a new module:

  1. navigate to Corteza Low Code,

  2. enter the namespace administration area,

  3. navigate to the "Modules" sub-page,

  4. click on the edit icon next to the module you wish to share,

  5. click on "Federation Settings",

  6. go to the "Expose" tab,

  7. select a node you wish to share the module to,

  8. select the fields you wish to share with the module,

  9. save the changes.

You can copy "Exposed" settings from other nodes by selecting the desired node from the "Copy settings from" dropdown.
Screenshot of the configuration window.
Figure 1. A screenshot showing the module sharing interface.

Consume shared data

A destination node can consume shared data from it’s paired origin node.

A destination node defines what modules it wishes to access and how values map in the destination module.

You can only consume data from nodes that we successfully paired.
Consuming data:

  1. navigate to Corteza Low Code,

  2. enter the namespace administration area,

  3. navigate to the "Modules" subpage,

  4. click on the edit icon next to the module you wish to consume data into,

  5. click on "Federation Settings",

  6. go to the "Map" tab,

  7. select a node you wish to consume the data from,

  8. select what shared fields map into what module fields,

  9. save the changes.

Screenshot of the configuration window.
Figure 2. A screenshot showing the module mapping interface.