Merge pull request #26 from oracle-samples/apex_update

feat: ✨ Added the ability to create and delete IoT Platform objects.

Author: wsanders00

apex/dashboard/CHANGELOG.md

@@ -1,6 +1,24 @@
+<!-- markdownlint-disable MD024 -->
 # IoT Explorer - Release Notes
 
-## September 16th 2025
+## October 17th, 2025
+
+### New Features
+
+- Creation and deletion available for models, adapters, and instances.
+- Secrets and certificates can be created as part of the instance
+  creation form.
+
+### Changes
+
+- DTDL Model D in Adapter and Instance reports links to Model Detail and
+Usage page.
+
+### Bug Fixes
+
+- Report column names and order consistency
+
+## September 16th, 2025
 
 ### New Features
 
@@ -15,16 +33,16 @@
 
 ### Bug Fixes
 
-- Report column names and order consistancy
+- Report column names and order consistency
 
-## August 25th 2025
+## August 25th, 2025
 
-### Inital Release
+### Initial Release
 
 Features
 
 - Traffic monitoring dashboard
-- Listing of OcI IoT Platform objects (models, adapters, and instances)
+- Listing of OCI IoT Platform objects (models, adapters, and instances)
 - Reports of Raw Data, Errors, and Historized data
-- Dynamic tree structure of OCI IoT Platform objects, their relationships, and most
-recent data collected
+- Dynamic tree structure of OCI IoT Platform objects, their relationships, and
+  most recent data collected

apex/dashboard/README.md

@@ -1,61 +1,119 @@
-
 # OCI IoT Platform Explorer
 
 This APEX application serves as a dashboard for monitoring IoT devices and messages.
 
 ## Prerequisites
 
-1. Complete setup of Iot Platform including access to APEX:
-2. Create an APEX user to install and access the application.
-
-Documentation about creating APEX users can be found in the
+1. Setup of IoT Platform. [IoT Platform Getting Started](https://docs.oracle.com/en-us/iaas/Content/internet-of-things/overview.htm)
+2. Allow access to APEX. [APEX Setup](https://docs.oracle.com/en-us/iaas/Content/internet-of-things/connect-iot-apex.htm)
+3. Create an APEX user to install and access the application.
 [APEX Administration Guide](https://docs.oracle.com/en/database/oracle/apex/24.2/aeadm/managing-users-across-an-application-express-instance.html#GUID-CE23292D-05D1-4E79-BF40-8BC31E74E6C8).
 
-### Optional
+### Enabling Optional Features
+
+The application includes the following optional features that require OCI
+credentials to function.
+
+1. Creation and deletion of models, adapters, and instances.
+2. Creation of certificates and passwords for instances created in the
+   application.
+3. retrieval of passwords stored in a vault and private keys of certificates to
+   facilitate device setup.
+4. retrieval of IoT Domain Group and IoT Domain information where the
+   application is running.
+
+>[!WARNING]
+>Providing these settings gives a group access to your IoT domain group(s),
+>the IoT domain(s) they contain, as well as certificates, private keys, and
+>other Vault secrets.
+>
+>**All users with access to the IoT Platform Explorer application will be able
+>to view this sensitive information**.
+>
+>This application is for demonstration purposes only and you should carefully
+>consider the access it provides, should you decide to configure these
+>settings.
+
+In order to mitigate some risk it is **recommended** that you create a
+dedicated OCI user and group that OCI IoT Explorer can use to access OCI REST
+APIs.
+
+1. Begin by creating an OCI user group.
+2. Next, create a user with an API Key assigned to that group.
 
-It is recommended that you create an OCI user and group that OCI IoT Explorer can use to
-access OCI REST APIs. However, any user with sufficient access will suffice.
+Then, as the admin-level user, create a new policy and set the policy
+statements appropriate for you.
 
-1. Begin by creating an OCI user group.  
-2. Next, create a user with an API Key assigned to that group.
+- Allow access read IoT Domain Group and Domain information
+
+  ```text
+  Allow group <grp_name> to read iot-family in compartment <cmp_name>
+  ```
+
+- Allow group members to create IoT objects. (models, adapters, instances,
+relationships )
+
+  ```text
+  Allow group <grp_name> to manage iot-digital-twin-family in compartment
+  <cmp_name>
+  ```
 
-Then, as the admin-level user, create a new policy and set the following.
+- Allow group members access, create, and read secrets stored in a vault.
 
-```text
-Allow group <grp_name> to manage iot-family in compartment <cmp_name>
-Allow group <grp_name> to manage iot-domain-family in compartment <cmp_name>
-Allow group <grp_name> to manage iot-digital-twin-family in compartment <cmp_name>
-```
+  ```text
+  Allow group <grp_name> to use vaults in compartment <cmp_name>
+  Allow group <grp_name> to manage secret-family in compartment <cmp_name>
+  Allow group <grp_name> to use keys in compartment <cmp_name>
+  ```
+
+- Allow group members to access and read certificate authority information and;
+  access, read, and create certificates.
+
+  ```text
+  Allow group <grp_name> to read certificate-authority-family in compartment
+  <cmp_name>
+  Allow group <grp_name> to use certificate-authority-delegate in compartment
+  <cmp_name>
+  Allow group <grp_name> to manage leaf-certificate-family in compartment
+  <cmp_name>
+  Allow group <grp_name> to use key-delegate in compartment <cmp_name>
+  ```
 
 ## Setup
 
-After completing your IoT Platform setup, you should be able to access your APEX
-instance with the user you created in the prerequisites. Log in to your instance and
-complete the following tasks to install the dashboard.
+After completing your IoT Platform setup, you should be able to access your
+APEX instance with the user you created in the prerequisites. Log in to your
+instance and complete the following tasks to install the dashboard.
 
 ### Part One
 
 There are several database objects that need to be created that are
-prerequisites for the IoT Explorer. The iot_explorer.sql file is a creation script
-for creating the following objects.
-
-* Synonyms
-  * A synonym will be created in the *__wksp schema for each of the views in the
-  *__iot schema. The synonym names are derived by removing 'DIGITAL_TWIN_' from the
-  view name (if present) and appending '_syn'.
-* Views
-  * iot_stats - merges messages/records that have occured after the last refresh of
-  iot_msg_stats to report basic stats for all data.
-  * iot_hierarchy - a hierarchy view of models -> adapters -> instances.
-* Materialized Views
-  * iot_msg_stats - computes basic stats on raw messages, rejected messages,
-  historized records, and command records.
-* Scheduled Tasks
-  * REFRESH_MVIEW_IOT_MSG_STATS - task is executed daily at 01:00 (1:00 am) and
-  updates the iot_msg_stats materialized view.
-* Functions
-  * compact_number( n number ) - accepts a number and returns a shorter string
-  representation of that number.
+prerequisites for the IoT Explorer. The iot_explorer.sql file is a creation
+script for creating the following objects.
+
+- Synonyms
+  - A synonym will be created in the *__wksp schema for each of the views in
+    the \*__iot schema. The synonym names are derived by removing
+    'DIGITAL_TWIN_' from the view name (if present) and appending '_syn'.
+
+- Views
+  - iot_stats - merges messages/records that have occurred after the last
+    refresh of iot_msg_stats to report basic stats for all data.
+  - iot_hierarchy - a hierarchy view of models -> adapters -> instances.
+  - auth_view - lists certs and secrets accessible to IoT.
+  - iot_certs - detailed information about certs available to IoT.
+  - iot_passwords - detailed information about passwords stored in the vault.
+
+- Materialized Views
+  - iot_msg_stats - computes basic stats on raw messages, rejected messages,
+    historized records, and command records.
+
+- Scheduled Tasks
+  - REFRESH_MVIEW_IOT_MSG_STATS - task is executed daily at 01:00 (1:00 am) and
+    updates the iot_msg_stats materialized view.
+
+- Packages
+  - See [iot_explorer_packages.md](iot_explorer_packages.md)
 
 #### Instructions
 
@@ -81,16 +139,16 @@ application number.
 
 ## Running the Application
 
-The application is accessable through any standard web browser via a url. To
-obtain that url use the instructions below.
+The application is accessible through any standard web browser via a URL. To
+obtain that URL use the instructions below.
 
 1. From the APEX home screen, click "App Builder".
 2. Then click "OCI IoT Platform Explorer".
 3. Then, click the "Run" button located at the top right of the page below your
 username.
-4. Copy and save / bookmark the url.
+4. Copy and save / bookmark the URL.
 
-The application uses APEX user account for authorization.
+The application uses an APEX user account for authorization.
 
 ## Usage
 
@@ -104,8 +162,8 @@ in a hierarchy starting with models, next adapters, then digital twins.
 
 The 'Settings' page allows you to enter a user's credentials and information
 about your tenancy.  This information, along with OCI policies allows the
-application to make the REST API calls to the IoT service. Any features requiring a
-value that has not been set will display a message to that effect.
+application to make the REST API calls to the IoT service. Any features requiring
+a value that has not been set will display a message to that effect.
 
 ## Removal
 

apex/dashboard/iot_explorer.app.sql

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:007df5138ee8fb979636739cdf20bbf3823fa1d9015ab70350d7d264eb8e7771
-size 845208
+oid sha256:5fe5982ade7b4478e63bf4db245bacabf91618932811beec56947b4d35d78e82
+size 1331625