Merge branch 'dev' into revert-1619-revert-1615-revert-1613-ws-patch-1

en/.spelling

@@ -89,10 +89,12 @@ liveness
 readingListApp
 ORGANIZATION_ID
 Petstore
+approvers
 build-your-first-cloud-native-application-with-choreo
 expose-a-service-as-a-managed-api
 build-your-first-integration
 configure-a-user-store-with-built-in-idp
+configure-approvals-for-choreo-workflows
 assign-subscription-plans-to-apis
 devops-and-ci-cd
 autoscale-component-replicas

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

@@ -0,0 +1,37 @@
+# Configure Approvals for Choreo Workflows
+
+Choreo allows you to configure approval processes for specific workflows within the platform. An approval process for a workflow ensures that critical or sensitive changes are properly managed and controlled.
+
+Choreo currently allows you to configure approvals for environment promotion workflows, with support for API subscription approvals coming soon.
+
+## Permissions to review and respond to approval requests
+
+To review and respond to 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**: Grants access to view and approve workflow requests. Each workflow type has a separate permission.
+  - **PROJECT-MANAGEMENT**: Grants access to view and approve workflow requests. This is the same permission used to update or delete projects.
+
+## 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.
+
+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.
+
+    - 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 **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.
+
+    !!! 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.
+
+Once you configure an approval process for a workflow, 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. Depending on the workflow, there can be tasks where the execution may occur automatically upon approval.

en/docs/administer/review-workflow-approval-requests.md

@@ -0,0 +1,31 @@
+# Review Workflow Approval Requests
+
+In Choreo, administrators can [configure approvals for workflows](./configure-approvals-for-choreo-workflows.md) and assign specific users as approvers.
+
+If you are assigned as an authorized reviewer for a particular workflow approval request, you will receive an email notification when a [request is submitted for approval](../develop-components/submit-and-manage-workflow-approval-requests.md). The email includes a summary of the request and a link to the **Approvals** page in the Choreo Console, where you can review the details and either approve or reject the request.
+
+!!! note
+     - Workflow approvals are managed at the project level. If a role with the necessary permissions is assigned in a project context, only members of the user group bound to that role within the specific project will receive notifications for requests made in that project. For example, if you are assigned the Project Admin role (which includes the necessary permissions) for project A, you will only be notified of workflow requests within project A.
+     - Users with organization-level permissions will receive notifications for all workflow requests across any project in the organization.
+
+Other approvers within your organization will also receive notifications for workflow requests and may review a request before you. If a request has already been reviewed, it will appear under the **Past** tab on the **Approvals** page.
+
+Approval requests are submitted on behalf of the team. Once approved, any authorized team member can execute the task. For certain tasks, execution may occur automatically upon approval.
+
+## View workflow approval requests
+
+To view workflow approval requests assigned to you, follow these steps:
+
+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 **Approvals**. This opens the **Approvals** page where you can see all approval requests assigned to you. The **Pending** tab lists requests that are yet to be reviewed. The **Past** tab displays requests already reviewed by you or other approvers, as well as requests canceled by the requester.
+4. To view details of a specific request, click **Review** corresponding to it.
+
+## Approve or reject an approval request
+
+To approve or reject a request, follow these steps:
+
+1. Follow the instructions in the [View workflow approval requests](#view-workflow-approval-requests) section above to see details of the workflow you want to review.
+   Alternatively, click the Choreo Console link in the approval request email notification you received. This takes you to the request details in the Choreo Console.
+2. Review the request and click **Approve** or **Reject** based on your decision.
+

en/docs/develop-components/submit-and-manage-workflow-approval-requests.md

@@ -0,0 +1,34 @@
+# Submit and Manage Workflow Approval Requests
+
+In Choreo, if an administrator [configures a workflow to require approval](../administer/configure-approvals-for-choreo-workflows.md), you must submit a request to obtain approval to perform the task.
+
+Upon submitting a workflow approval request, Choreo notifies all authorized assignees via email about the [review request](../administer/review-workflow-approval-requests.md). When an authorized assignee approves or rejects the request, you will receive an email with details of the decision.
+
+The approach to request approval can vary depending on the workflow. 
+
+## Request approval for environment promotion
+
+**Prerequisites**:
+
+- Ensure you have a component created, built, and deployed to the development environment.
+- Ensure that an approval workflow is configured for environment promotion.
+- Ensure you are promoting the component to a critical environment, such as production.
+
+To request approval to promote a component from the development environment to production, follow these steps:
+
+1. Sign in to the [Choreo Console](https://console.choreo.dev/).
+2. In the **Component Listing** pane, click on the component you want to deploy. This takes you to the **Overview** page of the component.
+3. In the left navigation menu, click **Deploy**.
+4. Go to the **Development** card and click **Request to Promote**.
+5. In the **Request Approval** pane that opens, enter your request details and click **Submit**. This creates a request and notifies all authorized assignees via email about the request.
+
+    !!! note
+         When an environment promotion request for a specific component is pending review, Choreo restricts other developers from making the same request until the pending request is either approved or rejected.
+
+When an authorized assignee approves the request, you will receive a confirmation email and can proceed to promote the component to production.
+
+## Cancel a workflow approval request
+
+If you want to cancel a workflow approval request that is already submitted, you can do so before the request is approved or rejected. 
+
+When you submit a workflow approval request, the **Request to Promote** button changes to **Cancel Request**. To cancel an approval request, click **Cancel Request**. Upon confirming the cancellation, all configured approvers are notified immediately, and the request will no longer be pending.

en/mkdocs.yml

@@ -129,6 +129,7 @@ nav:
       - Manage Deployment Tracks for Choreo Components: develop-components/manage-deployment-tracks-for-choreo-components.md
       - Configure Endpoints: develop-components/configure-endpoints.md
       - Manage Component Source Configurations: develop-components/manage-component-source-configurations.md
+      - Submit and Manage Workflow Approval Requests: develop-components/submit-and-manage-workflow-approval-requests.md
       - Develop Components Using VS Code: develop-components/develop-components-using-vs-code.md
   - Integrate and Manage External Services: 
       - Integrate and Manage Third-Party Services: integrate-and-manage-external-services/integrate-and-manage-third-party-services.md
@@ -212,6 +213,8 @@ nav:
           - Configure Asgardeo as an External IdP: administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp.md
           - Configure Azure as an External IdP: administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md
       - Create API Subscription Plans: administer/create-api-subscription-plans.md 
+      - Configure Approvals for Choreo Workflows: administer/configure-approvals-for-choreo-workflows.md
+      - Review Workflow Approval Requests: administer/review-workflow-approval-requests.md 
       - Configure a User Store with the Built-In Identity Provider: administer/configure-a-user-store-with-built-in-idp.md
       - Developer Portal:
           - Customize the Developer Portal: administer/customize-the-developer-portal.md