Merge pull request #1853 from abeykoon/update-worklow-configure-doc

Update workflow documentation with new config changes

Author: uvindra

en/developer-docs/docs/administer/configure-approvals-for-choreo-workflows.md

@@ -4,7 +4,7 @@ Choreo allows you to configure approval processes for specific workflows within
 
 Choreo currently allows you to configure approvals for environment promotion, API subscription and URL customization workflows.
 
-Configuring approvals for environment promotion allows authorized users to control components being promoted to a critical/production environment. 
+Configuring approvals for environment promotion allows authorized users to control components being promoted to a critical/production environment.
 
 Configuring approvals for the API subscription workflow allows you to create subscription plans that require approval before being activated. This feature allows you to control access to APIs by requiring administrative review and authorization of subscriptions before they become active.
 
@@ -18,61 +18,66 @@ Click the respective tab for details on permissions depending on the workflow fo
 
      To review and respond to environment promotion approval requests, a user must have the following permissions. Administrators must ensure that users designated to review and respond to approval requests have these permissions:
 
-      - **WORKFLOW-MANAGEMENT**: 
+      - **WORKFLOW-MANAGEMENT**:
           - Approve component promotion requests: Grants access to review and approve the promotion of components to critical environments.
-      - **PROJECT-MANAGEMENT**: Grants access to view and approve workflow requests. This is the same permission used to update or delete projects.
 
 === "API subscription"
 
      To review and respond to API subscription approval requests, a user must have the following permissions. Administrators must ensure that users designated to review and respond to approval requests have these permissions:
 
       - **WORKFLOW-MANAGEMENT**:
           - Approve API subscriptions: Grants access to review and approve API subscription workflow requests.
-      - **PROJECT-MANAGEMENT**: 
-          Grants access to view and approve workflow requests. This is the same permission used to update or delete projects.
 
 === "URL customization"
 
      To review and respond to URL customization approval requests, a user must have the following permissions. Administrators must ensure that users designated to review and respond to approval requests have these permissions:
 
       - **WORKFLOW-MANAGEMENT**:
           - Approve custom URL mapping requests: Grants access to review and approve custom URL mapping requests.
-      - **URL-MANAGEMENT**: 
+      - **URL-MANAGEMENT**:
           - Manage Custom Domains: Grants access to manage custom domains for the organization.
 
+!!! note
+     Approval permissions can be given to users in organization scope or project scope (by assigning user groups to roles at project level). Users having project level permissions can see and review approval requests originated from permitted projects only.
+
 ## Set up an approval process for a workflow
 
 To set up an approval process for a workflow, follow these steps:
 
 !!! note
      - You must have administrator privileges in Choreo to configure workflow approvals.
-     - Administrators can designate specific roles and assignees to review and respond to requests associated with each workflow.
+     - Administrators can designate specific roles and assignees to receive notifications associated with each workflow.
 
 1. Sign in to the [Choreo Console](https://console.choreo.dev/).
 2. In the Choreo Console header, go to the **Organization** list and select your organization.
 3. In the left navigation menu, click **Settings**. This opens the organization-level settings page.
 4. Click the **Workflows** tab.
-5. Click the edit icon corresponding to the workflow for which you want to configure an approval.
-6. In the **Configure Workflow** dialog that opens, select roles and assignees to review and respond to workflow approval requests.
+5. Click the Configure icon corresponding to the workflow for which you want to configure an approval.
+6. In the **Configure Workflow** dialog that opens, enable the workflow and optionally select roles and assignees to receive notifications on workflow approval requests.
 
-    - In the **Roles** field, select one or more roles depending on your preference. Any user assigned to these roles can review and respond to requests.
+    - In the **Roles** field, select one or more roles depending on your preference. All users assigned to the selected roles will be eligible to receive notifications. Scope of notification delivery depends on the role assignment level when [configuring permissions](#permissions-to-review-and-respond-to-approval-requests):
+         1. Project level roles-to-group assignment: Users in these groups will receive notifications only for approval requests raised within the specific project where the role is assigned.
+         2. Organization level roles-to-group assignment: Users in these groups will receive notifications for approval requests raised across all projects in the organization.
     - In the **Assignees** field, select specific users who can review and approve workflow requests. Assignees can be any Choreo user, even if they are not assigned to a selected role.
 
+    Both Roles and Assignees are optional configuration fields. If neither is specified, the system will not dispatch any notifications. However, users with the necessary permissions can still log in to the system and review approval requests through the interface.
+
     !!! info "Important"
-         Currently, there is no validation to ensure that the specified roles and assignees have the necessary permissions to review and respond to requests. If the [required permissions](#permissions-to-review-and-respond-to-approval-requests) are not correctly configured, some users may receive email notifications but will be unable to review the requests.
-         
-7. Click **Save**. This configures and enables the approval process for the workflow.
+         Only roles having [relevant approval permission](#permissions-to-review-and-respond-to-approval-requests) can be selected to receive notifications, so that respective users can always review and respond to requests. However, users in Assignees field are there for notification purpose only, they may not have required priviledges to review and approve requests.
+
+
+7. Click **Save**. This configures notifications and enables the approval process for the workflow.
 
-Once you enable the approval process for a workflow, see the following details on how to submit a request for approval and the approval process. Click the respective tab depending on the workflow for which you enabled the approval process:  
+Once you enable the approval process for a workflow, see the following details on how to submit a request for approval and the approval process. Click the respective tab depending on the workflow for which you enabled the approval process:
 
 === "Environment promotion"
 
-     Once you configure an approval process for environment promotion, developers must [submit a request for approval to use the workflow](../develop-components/submit-and-manage-workflow-approval-requests.md). An authorized assignee must then [review and approve the request](./review-workflow-approval-requests.md) for a developer to proceed with the task related to the workflow.
+     Once you enable an approval process for environment promotion, developers must [submit a request for approval to use the workflow](../develop-components/submit-and-manage-workflow-approval-requests.md). An authorized assignee must then [review and approve the request](./review-workflow-approval-requests.md) for a developer to proceed with the task related to the workflow.
 
 === "API subscription"
 
-     Once you configure an approval process for API subscription, administrators can select the **Approval required** checkbox to create or update subscription plans to require approval. For details, see [Create API Subscription Plans](../administer/create-api-subscription-plans.md). API consumers using these plans must request approval to proceed. For details, see step 7 in [Subscribe to an API with a Subscription Plan](../api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan.md). An authorized approver must then [review and approve the request](./review-workflow-approval-requests.md) before the subscription is granted.
+     Once you enable an approval process for API subscription, administrators can select the **Approval required** checkbox to create or update subscription plans to require approval. For details, see [Create API Subscription Plans](../administer/create-api-subscription-plans.md). API consumers using these plans must request approval to proceed. For details, see step 7 in [Subscribe to an API with a Subscription Plan](../api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan.md). An authorized approver must then [review and approve the request](./review-workflow-approval-requests.md) before the subscription is granted.
 
 === "URL customization"
 
-     Once you configure an approval process for URL customization, developers must submit a request for approval to configure a custom URL for a component. Instead of being automatically deployed, the URL mapping will go into a pending state. An authorized approver must then [review and approve the request](./review-workflow-approval-requests.md) before the custom URL is activated for the respective component. 
+     Once you enable an approval process for URL customization, developers must submit a request for approval to configure a custom URL for a component. Instead of being automatically deployed, the URL mapping will go into a pending state. An authorized approver must then [review and approve the request](./review-workflow-approval-requests.md) before the custom URL is activated for the respective component.