[Doc] Clarify setting of permissions for workspace objects

docs/resources/permissions.md

@@ -291,6 +291,8 @@ resource "databricks_permissions" "dlt_usage" {
 
 Valid [permission levels](https://docs.databricks.com/security/access-control/workspace-acl.html#notebook-permissions) for [databricks_notebook](notebook.md) are: `CAN_READ`, `CAN_RUN`, `CAN_EDIT`, and `CAN_MANAGE`.
 
+A notebook could be specified by using either `notebook_path` or `notebook_id` attribute.  The value for the `notebook_id` is the object ID of the resource in the Databricks Workspace that is exposed as `object_id` attribute of the `databricks_notebook` resource as shown below.
+
 ```hcl
 resource "databricks_group" "auto" {
   display_name = "Automation"
@@ -306,7 +308,7 @@ resource "databricks_notebook" "this" {
   language       = "PYTHON"
 }
 
-resource "databricks_permissions" "notebook_usage" {
+resource "databricks_permissions" "notebook_usage_by_path" {
   notebook_path = databricks_notebook.this.path
 
   access_control {
@@ -324,12 +326,35 @@ resource "databricks_permissions" "notebook_usage" {
     permission_level = "CAN_EDIT"
   }
 }
+
+resource "databricks_permissions" "notebook_usage_by_id" {
+  notebook_id = databricks_notebook.this.object_id
+
+  access_control {
+    group_name       = "users"
+    permission_level = "CAN_READ"
+  }
+
+  access_control {
+    group_name       = databricks_group.auto.display_name
+    permission_level = "CAN_RUN"
+  }
+
+  access_control {
+    group_name       = databricks_group.eng.display_name
+    permission_level = "CAN_EDIT"
+  }
+}
 ```
 
+-> **Note**: when importing a permissions resource, only the `notebook_id` is filled!
+
 ## Workspace file usage
 
 Valid permission levels for [databricks_workspace_file](workspace_file.md) are: `CAN_READ`, `CAN_RUN`, `CAN_EDIT`, and `CAN_MANAGE`.
 
+A workspace file could be specified by using either `workspace_file_path` or `workspace_file_id` attribute.  The value for the `workspace_file_id` is the object ID of the resource in the Databricks Workspace that is exposed as `object_id` attribute of the `databricks_workspace_file` resource as shown below.
+
 ```hcl
 resource "databricks_group" "auto" {
   display_name = "Automation"
@@ -344,7 +369,7 @@ resource "databricks_workspace_file" "this" {
   path           = "/Production/ETL/Features.py"
 }
 
-resource "databricks_permissions" "workspace_file_usage" {
+resource "databricks_permissions" "workspace_file_usage_by_path" {
   workspace_file_path = databricks_workspace_file.this.path
 
   access_control {
@@ -362,8 +387,29 @@ resource "databricks_permissions" "workspace_file_usage" {
     permission_level = "CAN_EDIT"
   }
 }
+
+resource "databricks_permissions" "workspace_file_usage_by_id" {
+  workspace_file_id = databricks_workspace_file.this.object_id
+
+  access_control {
+    group_name       = "users"
+    permission_level = "CAN_READ"
+  }
+
+  access_control {
+    group_name       = databricks_group.auto.display_name
+    permission_level = "CAN_RUN"
+  }
+
+  access_control {
+    group_name       = databricks_group.eng.display_name
+    permission_level = "CAN_EDIT"
+  }
+}
 ```
 
+-> **Note**: when importing a permissions resource, only the `workspace_file_id` is filled!
+
 ## Folder usage
 
 Valid [permission levels](https://docs.databricks.com/security/access-control/workspace-acl.html#folder-permissions) for folders of [databricks_directory](directory.md) are: `CAN_READ`, `CAN_RUN`, `CAN_EDIT`, and `CAN_MANAGE`. Notebooks and experiments in a folder inherit all permissions settings of that folder. For example, a user (or service principal) that has `CAN_RUN` permission on a folder has `CAN_RUN` permission on the notebooks in that folder.
@@ -373,6 +419,9 @@ Valid [permission levels](https://docs.databricks.com/security/access-control/wo
 - All users (or service principals) have `CAN_MANAGE` permission for objects the user creates.
 - User home directory - The user (or service principal) has `CAN_MANAGE` permission. All other users (or service principals) can list their directories.
 
+A folder could be specified by using either `directory_path` or `directory_id` attribute.  The value for the `directory_id` is the object ID of the resource in the Databricks Workspace that is exposed as `object_id` attribute of the `databricks_directory` resource as shown below.
+
+
 ```hcl
 resource "databricks_group" "auto" {
   display_name = "Automation"
@@ -386,9 +435,27 @@ resource "databricks_directory" "this" {
   path = "/Production/ETL"
 }
 
-resource "databricks_permissions" "folder_usage" {
+resource "databricks_permissions" "folder_usage_by_path" {
   directory_path = databricks_directory.this.path
-  depends_on     = [databricks_directory.this]
+
+  access_control {
+    group_name       = "users"
+    permission_level = "CAN_READ"
+  }
+
+  access_control {
+    group_name       = databricks_group.auto.display_name
+    permission_level = "CAN_RUN"
+  }
+
+  access_control {
+    group_name       = databricks_group.eng.display_name
+    permission_level = "CAN_EDIT"
+  }
+}
+
+resource "databricks_permissions" "folder_usage_by_id" {
+  directory_id = databricks_directory.this.object_id
 
   access_control {
     group_name       = "users"
@@ -407,6 +474,8 @@ resource "databricks_permissions" "folder_usage" {
 }
 ```
 
+-> **Note**: when importing a permissions resource, only the `directory_id` is filled!
+
 ## Repos usage
 
 Valid [permission levels](https://docs.databricks.com/security/access-control/workspace-acl.html) for [databricks_repo](repo.md) are: `CAN_READ`, `CAN_RUN`, `CAN_EDIT`, and `CAN_MANAGE`.