Using the IoT Flow Runtime Editor

Use the OCI-integrated Node-RED editor to build and deploy flows, configure Oracle Database and OCI nodes, and collaborate with other authorized users.

Each IoT Flow Runtime provides a managed Node-RED editor.

Open the editor from the Flow Runtime details page in the OCI Console. OCI Console single sign-on authenticates you to the editor, so you don't need separate Node-RED credentials. If you need help finding the IoT Flow Runtimes, see Listing IoT Flow Runtimes.

The Node-RED editor, uses this format for the flow runtime endpoint:

https://<flow-runtime-short-id>.flows.iot.<region>.oci.customer-oci.com/

Your OCI IAM permissions determine whether you can view or edit the flows.

Working with Multiple Users

More than one authorized user can open and edit the same Flow Runtime. Each user works in a separate browser editor session; this isn't character-by-character collaborative editing.

If another user deploys changes while you have undeployed changes, you have the option to review and merge the newer deployed flow configuration before you deploy. Coordinate deployments and keep related work on separate flow tabs when possible. Separating work into tabs also makes changes easier to compare and merge. For more information, see Flow Structure.

Updating Flow Runtime Software

OCI IoT manages the software for a Flow Runtime, including the managed Node-RED runtime. Don't use the Node-RED Palette Manager to update the managed runtime. The Palette Manager manages permitted node modules.

When one or more Flow Runtimes require a software update, OCI sends an announcement that lists the affected region, Flow Runtime name, Flow Runtime OCID, and the Action required by deadline. Complete the update for each listed Flow Runtime by the deadline in its announcement.

Review upgrade notices in Announcements in the OCI Console. To receive announcements by email, configure an announcement subscription and its Notifications topic with the required email recipients. See Creating an Announcement Subscription.

Flow Runtime software updates migrate existing flow definitions. After an update, the palette can show new nodes and reorganized categories while retaining the saved node types used by existing flows. Review the node reference and verify the workload after updating.

Note

Plan for a short interruption. Flow processing pauses and the editor is unavailable while the Flow Runtime is deactivated and reactivated.
  1. Open the announcement and review the affected resources and deadline. To find a listed resource in the Console, see Listing IoT Flow Runtimes.
  2. Before updating, move any required files from the Flow Runtime's local file system to Autonomous Database, File Storage, or another persistent storage service. The local file system is ephemeral and files on it might be lost during deactivation or activation. Data stored in Autonomous Database and mounted File Storage file systems is retained. If you need another recovery point for the flow definitions, back up the current flows JSON.
  3. Deactivate the affected Flow Runtime and wait for the deactivation work request to complete and the lifecycle state to become Inactive.
  4. Activate the Flow Runtime to apply the pending software update. Wait for the activation work request to complete successfully and the lifecycle state to become Active. For work request states and details, see Work Requests for IoT Domain Groups, Domains, and Flow Runtimes.
  5. Open the editor and verify that the flows, Flow Runtime interface, Oracle nodes, and other permitted node modules used by the workload operate normally. If activation or flow execution fails, review the configured Flow Runtime logs.
Important

If you don't complete the update by the Action required by deadline, OCI deactivates the affected Flow Runtime. The Flow Runtime remains in the Inactive state until you activate it. Activating it applies the pending software update and returns it to service.

Backing Up and Restoring Flows

The Flows tab stores the Flow Runtime's one current, complete Node-RED flows.json configuration file. Adding another flows.json replaces that active configuration; it doesn't create a separately retained backup.

Save a point-in-time copy outside the Flow Runtime, such as in an Object Storage bucket. A File Storage mount makes files available to running flows and isn't required for this management-side backup.

Backing Up the JSON Flows Configuration

  1. In the Node-RED editor, export the complete flow JSON configuration and download the JSON file. You can instead retrieve the active flows JSON from the Flow Runtime by using the Console, CLI, or API.
  2. Create an Object Storage bucket or select an existing backup bucket. Enable object versioning when you want Object Storage to retain earlier versions that use the same object name.
  3. Upload the JSON file. Use a name that identifies the Flow Runtime and backup time, for example flow-runtimes/<flow-runtime-short-id>/2026-07-28T160000Z-flows.json.
  4. Record the Flow Runtime OCID, Node-RED version, export time, and reason for the backup. Download the object and confirm that it contains valid JSON before depending on it for recovery.

Restoring the JSON Flows Configuration

  1. Retrieve and externally save the current flows JSON configuration before replacing it.
  2. Download the point-in-time JSON configuration that you want to restore from Object Storage.
  3. Add the JSON on the Flows tab, or replace the complete flows JSON by using the CLI or API. If you need help finding flows, see Listing IoT Flow Runtimes.
  4. Open the Node-RED editor and verify the flows, shared configuration nodes, and installed node modules. Reenter any required credentials that the exported JSON didn't preserve, and test critical flows.
Important

The flows JSON can contain sensitive endpoint and configuration details and might not preserve every secret required by credential-backed nodes. Limit access to backup objects and test the restore process before relying on it for recovery.

Oracle Nodes

The updated managed palette organizes OCI nodes into IoT, Messaging, Services, Streaming and Observability categories. It also provides Oracle Database nodes and a permitted Oracle Fusion Cloud SCM add-on. For each node's purpose, configuration and message inputs/results, see the Flow Runtime Node Reference.

A node module can be installed while individual nodes are disabled. Certificate and Vault Secret are installed but disabled by default. Collapsing a palette category only hides its entries; it does not disable its nodes.

Oracle Database Nodes

Use the database nodes for SQL, Oracle AQ enqueue/dequeue, and managed transactions. Select the shared DB Connection configuration. See Oracle Database Nodes.

OCI Nodes

Use OCI Config for signed OCI service requests, including Send Command and Get Content. Use the separate IoT Device configuration for MQTT Telemetry and Subscribe. See Shared Configuration Nodes and the category tables in the node reference.

OCI Config Options

The shared OCI Config node (oci-config) supplies request-signing authentication for OCI service nodes. The separate iot-config node holds an MQTT device connection. Select the OCI authentication type appropriate for the flow:

Authentication type Description
Config File Uses an OCI SDK configuration file and the selected profile.
Instance Principal Uses the identity of the OCI compute instance when an instance principal is available to the runtime environment.
Resource Principal Uses the Flow Runtime resource principal. This option avoids storing a user's long-lived credentials in the flow. Add the Flow Runtime to a dynamic group and grant only the policies required for the OCI resources that its nodes access.
API Key (Simple) Uses OCI user API-signing key information supplied to the configuration node. Protect these credentials and use a resource principal instead when the target service supports it.

OCI credential references supply values to supported credential fields; they are not an additional authentication type in this list. To use a Vault secret or certificate OCID instead of a literal credential value, see Using OCI References for Flow Credentials.

Set Region to the region containing the target resources. Compartment OCID supplies the default metric compartment for Monitoring Publish and Monitoring Query when their message and node settings omit it. Other service nodes use their own resource identifiers.

After changing the configuration, select Update, select Deploy, and then use Test OCI Credentials.

Using OCI References for Flow Credentials

Use an OCI resource OCID in a supported node credential field instead of entering the credential value directly. Flow Runtime stores the reference as entered and resolves it for the running node when the flow is deployed or starts. Literal credential values remain supported.

Literal credentials saved in the flows document are encrypted at rest. This is different from storing uploaded key or certificate files on the Flow Runtime's local file system, which is ephemeral; see Updating Flow Runtime Software. With an OCI reference, the flows document stores the reference rather than the credential value.

References are supported in credential fields on nodes and configuration nodes, and in credential-type environment variables used by supported nodes. An OCID in an ordinary node property, a message, or Function code isn't resolved as a credential.

Credential references in supported fields are separate from the Certificate and Vault Secret nodes. A credential reference supplies a value to the consuming node without requiring a flow to retrieve the secret or certificate into a message.

Reference Format and Supported Resources

<resource-OCID>[#<JSON-pointer>]

Replace <resource-OCID> with the OCID of the secret, certificate, or certificate authority. A JSON Pointer begins with /, follows RFC 6901, and must select a string value. Certificate and certificate authority references require a pointer.

ResourceSupported pointer
Vault secret (ocid1.vaultsecret)Optional. Use the bare secret OCID for a plaintext secret, or a pointer such as #/password or #/services/payment/apiToken for a string in a JSON secret.
Certificate (ocid1.certificate)#/certificatePem, #/certChainPem, #/privateKeyPem, or #/privateKeyPemPassphrase
Certificate authority (ocid1.certificateauthority)#/certificatePem or #/certChainPem

Other OCID resource types aren't supported as credential references. For example, use a secret OCID, not its vault or encryption-key OCID.

Prefer explicit pointers for JSON secrets. Mapping an entire JSON secret to a credential object requires string values whose keys exactly match the node's complete credential-field set.

Grant Access to the Referenced Resources

Add the Flow Runtime to a dynamic group and grant that group access to the resources its flows require. These permissions are for the Flow Runtime resource principal, not the user's editor session or a digital twin device's authentication identity.

Values in angle brackets, such as <flow-runtime-dynamic-group>, are placeholders that you replace manually. They are not environment variables and are not filled in automatically. Replace the complete placeholder, including the angle brackets, with a value from your tenancy.

PlaceholderReplace WithExample Value
<flow-runtime-dynamic-group>The name of the dynamic group that contains your Flow Runtime.iot-flow-runtimes
<secret-compartment>The name of the compartment containing the referenced Vault secret.iot-secrets
<secret-OCID>The full OCID copied from that secret's details. Use the secret OCID, not the vault or encryption-key OCID.ocid1.vaultsecret.oc1.iad.exampleuniquesecretid
<certificate-compartment>The name of the compartment containing the referenced certificate.iot-certificates
<ca-compartment>The name of the compartment containing the referenced certificate authority.iot-ca

target.secret.id and target.leaf-certificate.bundle-type are IAM condition variables evaluated by OCI for the request. Keep these variable names unchanged. Keep the fixed bundle-type value CERTIFICATE_CONTENT_WITH_PRIVATE_KEY unchanged, and retain the single quotation marks around it and the secret OCID.

For a single secret, replace the placeholders in this policy:

Allow dynamic-group <flow-runtime-dynamic-group> to read secret-bundles in compartment <secret-compartment> where target.secret.id = '<secret-OCID>'

For example, after substituting the dynamic group, compartment and secret OCID, the policy looks like this. The names and OCID below are illustrative; replace them with your actual values:

Allow dynamic-group iot-flow-runtimes to read secret-bundles in compartment iot-secrets where target.secret.id = 'ocid1.vaultsecret.oc1.iad.exampleuniquesecretid'

This example grants the named dynamic group permission to read the bundle for that one secret. See the Vault and Secret Management policy reference for the supported variables and permissions.

For certificate and certificate authority references, grant the applicable bundle permissions in their resource compartments:

Allow dynamic-group <flow-runtime-dynamic-group> to read leaf-certificate-bundles in compartment <certificate-compartment> where target.leaf-certificate.bundle-type = 'CERTIFICATE_CONTENT_WITH_PRIVATE_KEY'
Allow dynamic-group <flow-runtime-dynamic-group> to read certificate-authority-bundles in compartment <ca-compartment>

Using the example names from the table, the certificate and certificate-authority policies become:

Allow dynamic-group iot-flow-runtimes to read leaf-certificate-bundles in compartment iot-certificates where target.leaf-certificate.bundle-type = 'CERTIFICATE_CONTENT_WITH_PRIVATE_KEY'
Allow dynamic-group iot-flow-runtimes to read certificate-authority-bundles in compartment iot-ca

Replace iot-flow-runtimes, iot-certificates and iot-ca with your own names before using these examples. These certificate policies apply to the specified bundle types in the named compartments; the secret policy above is restricted to one secret OCID.

The certificate reference retrieves a bundle containing its private key. Restrict access to the required resources and review the Certificates service policy reference before granting private-key access.

Enter a Reference in the Editor

  1. Open the node or configuration-node editor.
  2. Enter a reference in a supported credential field. For HTTP Basic authentication, prefer a plain-text username such as example-user and a secret reference for the password:
    <secret-OCID>#/password
    For a plaintext secret containing a bearer token or password, enter the secret OCID without a pointer.
  3. For TLS client authentication, use the applicable references:
    CredentialReference
    Client certificate<certificate-OCID>#/certificatePem
    Private key<certificate-OCID>#/privateKeyPem
    CA certificate<certificate-authority-OCID>#/certificatePem
    Private-key passphrase, when requiredThe OCID of a plaintext Vault secret containing the passphrase.
    Use a certificate whose bundle includes the required certificate and private-key values. Use a certificate authority reference for the CA credential.
  4. Select Done, and then select Deploy.
  5. Test the intended connection. Verify authentication and the expected destination without logging the resolved credential or private key.

Reuse a Reference with a Credential Environment Variable

  1. Open the editor menu, select User Settings, and then select Environment.
  2. Add a global environment variable, select Credential as its type, enter the OCI reference as its value, and save the setting. For example, set TLS_CLIENT_CERT to <certificate-OCID>#/certificatePem.
  3. In a supported node field, select the environment variable. For a tls-config node, choose Environment Variable as the certificate type and select the variables for the required certificate, key, CA certificate, and optional passphrase fields.
  4. Deploy and test the flow.

Credential-type environment values are masked in User Settings. Flow Runtime resolves the reference before the consuming node evaluates the environment value.

Deployment, Refresh, and Troubleshooting

References are resolved at deployment or startup, not once per message. Don't assume that changing a referenced resource immediately refreshes a running flow. After a change, validate the refresh behavior of the specific credential and node before retiring the previous value.

To refresh referenced credentials used by HTTP Basic authentication or mutual TLS, redeploy the flow or deactivate and then activate the Flow Runtime. These actions refresh a directly referenced Vault password and imported client certificate, private key, and externally managed CA references configured through credential environment variables. Verify that authentication succeeds with the new credentials before retiring the previous values. This is not automatic refresh or a procedure for renewing an internally managed CA. A username reference is supported when needed, but a literal username and a separately stored password are recommended.

Malformed OCIDs, unsupported resource types, invalid pointers, missing pointer targets, and non-string results reject deployment. Check the reference type, pointer, resource permissions, and required bundle fields. Don't copy resolved secrets, PEM data, private keys, or authorization values into logs or support requests.

If you use the CLI or API to update flows, first retrieve and save the current flows document. Updating flows replaces the complete document; preserve its full content rather than submitting only a new credential fragment.

Managing Node Modules

In the managed Node-RED editor for an OCI IoT Flow Runtime, use the Palette Manager to view the list of available node modules, for a list of available nodes see Flow Runtime Node Reference. You can install modules only from this existing list. You can't add new modules to the list or install arbitrary modules from the public Node-RED library.