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.
OCI and Node-RED Navigation
The OCI navigation bar appears above the standard Node-RED editor header.
| Control | Description |
|---|---|
| <flow-runtime-short-id> | Returns to the Flow Runtime details page in the OCI Console. |
| Editor or Viewer | Shows your current access level. Editors can change and deploy flows. Viewers can inspect the editor but can't deploy changes. When multiple users are logged in, a message displays stating this flow is being updated by another user. The other user sees the option to review or merge changes. |
| Session remaining | Shows the time remaining in the authenticated editor session. |
| Extend | Select to extend the time in the authenticated editor session. |
| Help | Opens help for the editor. |
| Sign Out | Ends the editor session. |
The Node-RED header contains Deploy and the main menu. The editor contains the node palette on the left, the flow workspace in the center, and information, help, debug, configuration, and context sidebars on the right.
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.
Plan for a short interruption. Flow processing pauses and the editor is unavailable while the Flow Runtime is deactivated and reactivated.
- Open the announcement and review the affected resources and deadline. To find a listed resource in the Console, see Listing IoT Flow Runtimes.
- 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.
- Deactivate the affected Flow Runtime and wait for the deactivation work request to complete and the lifecycle state to become Inactive.
- 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.
- 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.
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
- 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.
- 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.
- 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. - 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
- Retrieve and externally save the current flows JSON configuration before replacing it.
- Download the point-in-time JSON configuration that you want to restore from Object Storage.
- 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.
- 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.
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 managed palette includes Oracle Database nodes and OCI nodes in addition to the standard Node-RED nodes. The nodes available in a Flow Runtime can depend on the service version.
Oracle Database Nodes
The db-nodes group connects flows to an Oracle Database, including a customer Autonomous Database when configured.
| Node | Description |
|---|---|
| db-connection | Defines a shared Oracle Database connection that the other database nodes use. |
| begin transaction | Obtains a database connection and begins a transaction for downstream database operations. |
| end transaction | Commits or rolls back the current transaction and releases its database connection. |
| enqueue | Adds a message to a configured Oracle Database transactional event queue. |
| dequeue | Retrieves a message from a configured Oracle Database transactional event queue. |
| sql | Runs a SQL statement by using the configured database connection. |
OCI Nodes
The oci-nodes group connects a flow to supported OCI IoT operations.
| Node | Description |
|---|---|
| iot-config | Defines the shared OCI Config authentication, region, and default compartment settings used by OCI nodes. |
| send command | Sends a command to a digital twin instance. |
| subscribe | Subscribes a flow to messages from a supported OCI IoT source. |
| telemetry | Sends telemetry from a flow to OCI IoT. |
OCI Config Options
The palette labels the shared configuration node iot-config. Its edit dialog uses the OCI Config label. Select the 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. Set Compartment OCID to the default compartment for child OCI nodes. A child node can override the default compartment.
After changing the configuration, select Update, select Deploy, and then use Test Connection.
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.
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.
| Resource | Supported 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.
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 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>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
- Open the node or configuration-node editor.
- Enter a reference in a supported credential field. For HTTP Basic authentication, prefer a plain-text username such as
example-userand a secret reference for the password:
For a plaintext secret containing a bearer token or password, enter the secret OCID without a pointer.<secret-OCID>#/password - For TLS client authentication, use the applicable references:Use a certificate whose bundle includes the required certificate and private-key values. Use a certificate authority reference for the CA credential.
Credential Reference Client certificate <certificate-OCID>#/certificatePemPrivate key <certificate-OCID>#/privateKeyPemCA certificate <certificate-authority-OCID>#/certificatePemPrivate-key passphrase, when required The OCID of a plaintext Vault secret containing the passphrase. - Select Done, and then select Deploy.
- 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
- Open the editor menu, select User Settings, and then select Environment.
- 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_CERTto<certificate-OCID>#/certificatePem. - In a supported node field, select the environment variable. For a
tls-confignode, choose Environment Variable as the certificate type and select the variables for the required certificate, key, CA certificate, and optional passphrase fields. - 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. 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.