Scenario: Working with an IoT Domain Group

An administrator must add a policy to your tenancy and the compartments you want to use. For policy examples and prerequisites, see Policy Details for the Internet of Things (IoT) Platform and IoT Prerequisites.

For a list of applicable resource limits and instructions for requesting a limit increase, see Limits on Internet of Things Resources.

You must set up a domain group before you create a domain. Each IoT domain group uses a dedicated database instance, that's shared by all IoT domains associated with the IoT domain group.

oci iot domain-group create --compartment-id <compartment-OCID> --display-name <your-iot-domain-group-name>

The example response shows the domain group is creating and contains the data host URL with a domain group short ID. Use the data host URL to access your metadata and data associated with a specific IoT domain group that contains all the devices for the associated IoT domain.

data-host:<domain-group-short-id>.data.iot.<region>.oci.oraclecloud.com

Notice the database connection details are null. After the domain group is created, depending on where you want to view your data you need to configure the associated IoT domain's data access to add the authentication details for the IoT domain to connect to another system.

{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "data-host": "<domain-group-short-id>.data-iot.<region>.oci.oraclecloud.com,
    "db-allow-listed-vcn-ids": null,
    "db-connection-string": null,
    "db-token-scope": null,
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-05T18:15:41.260Z"
      }
    },
    "description": null,
    "display-name": "<your-iot-domain-group-name>",
    "freeform-tags": {},
    "id": "<domain-group-OCID>",
    "lifecycle-state": "CREATING",
    "system-tags": {},
    "time-created": "2025-08-05T18:15:43.054000+00:00",
    "time-updated": "2025-08-05T18:15:43.054000+00:00"
  },
  "etag": "<unique-id>",
  "opc-work-request-id": "<work-request-OCID>"
            }

Optionally, during this process of working with a domain group, you can monitor each operation's work request to confirm if it succeeded before proceeding to the next operation. You can use work requests to check logs or error messages.

Use the "opc-work-request-id": "<work-request-OCID>" from any operation to get the related work request for that specific operation. For example:

oci iot domain-group get --iot-domain-group-id <iot-domain-group-OCID>

This example response shows the VCN is not configured for the IoT domain group:

{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "data-host": "<domain-group-short-id>.data.iot.us-phoenix-1.oci.oraclecloud.com",
    "db-allow-listed-vcn-ids": null,
    "db-connection-string": null,
    "db-token-scope": null,
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-08T09:29:22.092Z"
      }
    },
    "description": null,
    "display-name": "Demo Domain Group",
    "freeform-tags": {},
    "id": "<iot-domain-group-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-09-08T09:29:22.449000+00:00",
    "time-updated": "2025-09-08T09:38:01.413000+00:00"
  },
  "etag": "<unique-id>"
}

After an IoT domain group is active, if you want to establish a direct database connection to view the data directly in the database or if you want to connect your data to use Oracle Analytics Cloud, then as part of that configuration you must add a VCN or VCNs to allow access to IoT data for this domain group.

For a complete list of steps to configure a direct connection to the database, see Scenario: Connecting Directly to the IoT Database or to configure access to view your IoT data in Oracle Analytics Cloud see, Scenario: Connecting your IoT Data to Analytics Cloud.

Use the oci iot domain-group configure-data-access command to configure the VCN or VCNs that you want to allow access to the database for the domain group.

Replace the ["vcn-OCID-1","vcn-OCID-2"] with the VCN OCIDs configured for your environment. Replace the <domain-group-OCID> with the domain group's OCID that you want to work with:

For more information, see Configuring Data Access for an IoT Domain Group.

oci iot domain-group configure-data-access --db-allow-listed-vcn-ids '["vcn-OCID-1","vcn-OCID-2"]' --iot-domain-group-id <domain-group-OCID>

A maximum number of VCNs allowed is 5.

When working with an IoT domain group, you can use this command to get the domain group details. In the response, you can verify the database connection details for defined for this IoT domain group. Replace the <iot-domain-group-OCID> with the OCID for the specific IoT domain group:

oci iot iot-domain-group get --iot-domain-group-id <iot-domain-group-OCID>

This example response shows the domain group is active, "lifecycleState": "ACTIVE" and if configured this response includes the database connection details and the data host for the domain group:

db-allow-listed-vcn-ids

db-connection-string

db-token-scope

{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "data-host": "<domain-group-short-id>.iot-data.<region>.oci.oraclecloud.com",
    "db-allow-listed-vcn-ids": [
      "<vcn-OCID>"
    ],
    "db-connection-string": "tcps:adb.<region>.oraclecloud.com:1521/<unique-id>.adb.oraclecloud.com?retry_count=20&retry_delay=3",
    "db-token-scope": "urn:oracle:db::id::ocid1.<database-compartment-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-11T19:21:24.791Z"
      }
    },
    "description": "<your-domain-group-description>",
    "display-name": "<your-domain-group-name>",
    "freeform-tags": {},
    "id": "<iot-domain-group-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-11T19:21:26.411000+00:00",
    "time-updated": "2025-08-12T02:17:02.763000+00:00"
  },
  "etag": "<unique-id>"
          }

Next, create an IoT domain and associate the domain to a domain group.