Scenario: Working with an IoT Domain Group

This scenario explains IoT domain group workflow.

Before you begin

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.

Note

Oracle restricts creating up to 2 IoT domains in each IoT domain group. The maximum number of IoT domain groups is 5 and maximum number IoT domains is 10 for each region in your tenancy.

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

Step 1: Creating an IoT Domain Group

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.

To create a new IoT domain group, use this oci iot create-domain-group command and the required <compartment-OCID> parameter to create a domain group in the specific compartment. Optionally, you can include the display name.
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:

Optional: Getting a Work Request Before an IoT Domain Group is Created

Optionally, during the time it takes to create a domain group, you can get the work request to view the status of the creating an IoT domain group process.

  1. Use the oci iot work-request get command to get the work request for creating a domain group. Replace the <work-request-OCID> with the OCID for the work request in the response from the previous step:
    oci iot work-request get --work-request-id <work-request-OCID>
  2. If you get the work request during the time the create IoT domain group is processing, you see something like this example response that shows the creating a domain group process as accepted and successfully started, notice the following parameters in the example below:

    "operationType": "CREATE_IOT_DOMAIN_GROUP"

    "actionType": "IN_PROGRESS"

    "status": "ACCEPTED"

    {
      "data": {
        "compartment-id": "<compartment-OCID>",
        "id": "<iot-work-request-OCID>",
        "operation-type": "CREATE_IOT_DOMAIN_GROUP",
        "percent-complete": 50.0,
        "resources": [
          {
            "action-type": "IN_PROGRESS",
            "entity-type": "iotDomainGroup",
            "entity-uri": "/20250531/iotDomainGroups/<iot-domain-group-OCID>",
            "identifier": "<iot-domain-group-OCID>",
            "metadata": null
          }
        ],
        "status": "ACCEPTED",
        "time-accepted": "2025-09-08T09:29:22.505000+00:00",
        "time-finished": null,
        "time-started": null,
        "time-updated": "2025-09-08T09:29:57.532000+00:00"
      },
      "etag": "<unique-id>"
    }
    
    This example shows how to get a work request using the CLI. Alternatively, you can also use the Console or REST APIs to get the work request OCID. For more information, see Work Requests for IoT Domains and Domain Groups. You can find the work request OCID on the domain group details page using the Console. For more information, see Getting a Work Request's Details.
Optional: Listing an IoT Domain Group's Work Request Logs

Optionally, you can use the oci iot work-request list-logs command to verify if the creating a domain group work request displays the creating a domain group process described in the logs.

oci iot work-request list-logs --work-request-id <work-request-OCID>
This example response shows a list of logs from a creating a domain group work request:
{
  "data": {
    "items": [
      {
        "message": "Generating database credentials",
        "timestamp": "2025-09-08T09:29:48.410000+00:00"
      },
      {
        "message": "Creating database",
        "timestamp": "2025-09-08T09:29:54.543000+00:00"
      },
      {
        "message": "Provisioning database",
        "timestamp": "2025-09-08T09:29:57.532000+00:00"
      }
    ]
  }
}
Optional: Listing an IoT Domain Group's Work Request Errors

Optionally, use the oci iot work-request list-errors command to list any errors for the creating a domain group work request.

oci iot work-request list-errors --work-request-id <work-request-OCID>

If creating a domain group work request log entries exist, this is an example response. This example response does not contain any errors:

{
  "data": {
    "items": []
  }
}
    
Optional: Getting the Work Request After an IoT Domain Group is Created

After the creating a domain group operation is finished, use the oci iot work-request get command to confirm the domain group created successfully and to confirm the domain group is active.

oci iot work-request get --work-request-id <work-request-OCID>
This example response shows the "actionType": "CREATED" and the "status": "SUCCEEDED", confirming the domain group was created successfully.
{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "id": "<iot-work-request-OCID>",
    "operation-type": "CREATE_IOT_DOMAIN_GROUP",
    "percent-complete": 100.0,
    "resources": [
      {
        "action-type": "CREATED",
        "entity-type": "iotDomainGroup",
        "entity-uri": "/20250531/iotDomainGroups/<iot-domain-group-OCID>",
        "identifier": "<iot-domain-group-OCID>",
        "metadata": null
      }
    ],
    "status": "SUCCEEDED",
    "time-accepted": "2025-09-08T09:29:22.505000+00:00",
    "time-finished": "2025-09-08T09:38:01.360000+00:00",
    "time-started": "2025-09-08T09:29:48.402000+00:00",
    "time-updated": "2025-09-08T09:38:01.360000+00:00"
  },
  "etag": "<unique-id>"
}
Optional: Listing Work Request Logs After an IoT Domain Group is Created
Use this command to list the logs to confirm the process of creating an IoT domain group operation completed all the steps.
oci iot work-request list-logs --work-request-id <work-request-OCID>
This example response shows all the steps completed for the create an IoT domain group operation:
{
  "data": {
    "items": [
      {
        "message": "Generating database credentials",
        "timestamp": "2025-09-08T09:29:48.410000+00:00"
      },
      {
        "message": "Creating database",
        "timestamp": "2025-09-08T09:29:54.543000+00:00"
      },
      {
        "message": "Provisioning database",
        "timestamp": "2025-09-08T09:29:57.532000+00:00"
      },
      {
        "message": "Enabling data guard",
        "timestamp": "2025-09-08T09:33:59.906000+00:00"
      },
      {
        "message": "Configuring admin secret rotation ",
        "timestamp": "2025-09-08T09:37:03.396000+00:00"
      },
      {
        "message": "Generating DNS record(s)",
        "timestamp": "2025-09-08T09:37:08.842000+00:00"
      },
      {
        "message": "Configuring routing policy",
        "timestamp": "2025-09-08T09:37:09.903000+00:00"
      },
      {
        "message": "Finishing work request",
        "timestamp": "2025-09-08T09:38:01.360000+00:00"
      }
    ]
  }
}

Step 2: Getting the Details for an IoT Domain Group Before Adding VCN Details

Use this command to get the details for a specific IoT domain group.
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>"
}

Optional: Adding a VCN to the IoT Domain Group to Establish a Direct Database Connection

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.

Step 3: Getting the IoT Domain Group Details After Adding the VCN Details

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.