Updating a Digital Twin Instance

Update a digital twin instance's connectivity type, gateway associations, authentication ID, adapter, model, external key, name, description, or tags in Internet of Things (IoT).

You can change a digital twin instance between DIRECT, INDIRECT, and GATEWAY connectivity types. The destination configuration must be valid as a whole. Include the model, adapter, authentication ID, and gateway associations required by the destination connectivity type in the same update.

If you update the digital twin model, use a compatible model with the same DTMI path and major version as the current model. The minor version must be the same or higher. You can't switch to an unrelated model while changing the connectivity type.

For an end-to-end example that uses directly connected, indirectly connected, and gateway instances together, see Change a Digital Twin Instance Connectivity Type.

Connectivity Type Transition Requirements
Change to	Required settings	Restrictions
`DIRECT`	Specify an authentication ID. For structured data, use a digital twin adapter without gateway target mapping.	Gateway associations aren't allowed.
`INDIRECT`	Specify a nonempty list of gateway digital twin instance OCIDs. For structured data, use a digital twin adapter without gateway target mapping.	An authentication ID isn't allowed. Each gateway must be an existing active `GATEWAY` instance in the IoT domain. Don't include duplicate gateways or exceed gateway capacity.
`GATEWAY`	Specify an authentication ID and a digital twin adapter with gateway target mapping.	Gateway associations aren't allowed. Before changing an existing gateway to another connectivity type, reassign all indirectly connected digital twin instances that use it.

Note

The Console label Not connected corresponds to the API and CLI value NONE. You can't change an existing digital twin instance to NONE. To use this connectivity type, create a new digital twin instance and select Not connected in the Console or specify NONE with the API or CLI.

Updating an instance with its current connectivity type is idempotent.

Use the oci iot digital-twin-instance update command and the required parameters to update a digital twin instance.

Use --connectivity-type, --auth-id, --digital-twin-adapter-id, --digital-twin-model-id, --digital-twin-model-spec-uri, and --gateways to supply a valid destination configuration.

Change a directly connected instance to a gateway

Use this command to supply the gateway connectivity type, authentication ID, and an adapter with gateway target mapping.
```
oci iot digital-twin-instance update \
  --digital-twin-instance-id <digital-twin-instance-OCID> \
  --connectivity-type GATEWAY \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <gateway-adapter-OCID> \
  --force
```
Change an indirectly connected instance to directly connected

Use this command to provide the direct connectivity type, authentication ID, and adapter without gateway target mapping.
```
oci iot digital-twin-instance update \
  --digital-twin-instance-id <digital-twin-instance-OCID> \
  --connectivity-type DIRECT \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <direct-adapter-OCID> \
  --force
```
Change a gateway to directly connected

First reassign every indirectly connected digital twin instance that uses the gateway. Then use this command to supply the direct connectivity configuration.
```
oci iot digital-twin-instance update \
  --digital-twin-instance-id <gateway-instance-OCID> \
  --connectivity-type DIRECT \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <direct-adapter-OCID> \
  --force
```
Update other digital twin instance settings

Use this command and the required parameter to update a digital twin instance's external key. Avoid using quotes with an external key value.
```
oci iot digital-twin-instance update \
  --digital-twin-instance-id <digital-twin-instance-OCID> \
  --external-key <your-device-id>
```
Use this command and the required parameter to update a digital twin instance's authentication ID.
```
oci iot digital-twin-instance update \
  --digital-twin-instance-id <digital-twin-instance-OCID> \
  --auth-id <updated-certificate-or-secret-OCID>
```
For the complete list of parameters, see oci iot digital-twin-instance update. For all OCI CLI commands, see CLI Command Reference.
Run the UpdateDigitalTwinInstance operation to update a digital twin instance.

To change the connectivity type, set connectivityType in UpdateDigitalTwinInstanceDetails to DIRECT, INDIRECT, or GATEWAY. Include companion fields such as authId or gateways in the same request when the destination type requires them.

For example, change a directly connected instance to indirectly connected by clearing its authentication ID, selecting an adapter without gateway target mapping, and providing at least one gateway:
```
{
  "connectivityType": "INDIRECT",
  "authId": null,
  "digitalTwinAdapterId": "<direct-adapter-OCID>",
  "gateways": [
    "<gateway-instance-OCID>"
  ]
}
```

Troubleshooting Connectivity Type Updates

The destination configuration is rejected

An HTTP 400 response means that the requested connectivity type and its companion settings aren't valid together. Check the model compatibility, authentication ID, adapter target mapping, and gateway associations against the transition requirements on this page, and then submit the complete destination configuration again.

A gateway has indirectly connected dependents

An HTTP 409 response identifies indirectly connected digital twin instances that still use the gateway. Reassign those downstream instances to another gateway or change them to a supported connectivity type. After no indirectly connected instances depend on the gateway, retry the gateway update.

An indirectly connected update retains an authentication ID

Don't pass --auth-id null. The CLI treats null as text and rejects it as an invalid OCID. Use the UpdateDigitalTwinInstance operation with "authId": null when the update must explicitly clear the authentication ID.

An adapter doesn't match the destination type

For GATEWAY, select an adapter that defines gateway target mapping. For DIRECT or INDIRECT, select an adapter without gateway target mapping.

You need a Not connected instance

Changing an existing digital twin instance to NONE isn't supported. Instead, create a new digital twin instance with Not connected in the Console or NONE in the API or CLI.

Connectivity Type Update FAQs

Are Not connected and NONE the same connectivity type?: Yes. Not connected is the Console label. NONE is the corresponding API and CLI value.
Can I change an existing digital twin instance to Not connected?: No. Create a new digital twin instance with Not connected or NONE instead.
Can I change to a different digital twin model while changing connectivity?: Only when the model is compatible: it must use the same DTMI path and major version, and the same or a higher minor version. You can't switch to an unrelated model in the connectivity update.
Why can't I change a gateway to another connectivity type?: One or more indirectly connected digital twin instances still use it. Reassign those downstream instances, and then retry the gateway update.
Can I update an instance to its current connectivity type?: Yes. A same-type update is idempotent when the complete configuration remains valid.

Oracle Cloud Infrastructure Documentation