Update descriptions for workflow operations in Swagger

Signed-off-by: Mudit Garg <35302867+garg-mudit@users.noreply.github.com>

Author: garg-mudit

maestro.rest.swagger-v1.0.0.json

@@ -69,7 +69,7 @@
             "get": {
                 "operationId": "GetWorkflowsList",
                 "summary": "Retrieve a list of available Maestro workflows",
-                "description": "This operation retrieves a list of all available Maestro workflows. It returns basic information\nabout each workflow, including its unique identifier (`id`), name, description, and the input\nschema required to trigger the workflow.\n\nThe response provides key details that help users identify which workflows are available\nand understand the input requirements for triggering each one. Each workflow entry also includes\nmetadata, such as when it was created, last modified, and by whom.\n\nThis operation is useful for obtaining an overview of all workflows within the system, helping\nusers and systems know what workflows are defined, what inputs they require, and how they can\nbe triggered.\n\n### Use Cases:\n- Listing all available workflows in a system for manual or automated workflow initiation.\n- Reviewing the input requirements for a workflow before triggering it programmatically.\n- Gathering basic metadata about workflows for auditing, logging, or reporting purposes.\n\n### Key Features:\n- **Comprehensive Workflow Overview**: Provides a full list of workflows, giving visibility\n  into all the automated processes available within the Maestro platform.\n- **Input Schema Information**: Each workflow includes its trigger input schema, showing\n  what data must be provided when triggering the workflow.\n- **Metadata for Tracking**: Useful metadata like creation time, last modification date,\n  and user details are included to support tracking and auditing workflows.\n- **Future-Proof**: The operation is designed to be expandable as more workflows are added\n  or the platform grows, ensuring scalability in the workflow management process.\n",
+                "description": "This operation retrieves a list of all available Maestro workflows. It returns basic information\nabout each workflow, including its unique identifier (`id`), name, description, and the input\nschema required to trigger the workflow.\n\nThe response provides key details that help users identify which workflows are available\nand understand the input requirements for triggering each one. Each workflow entry also includes\nmetadata, such as when it was created, last modified, and by whom.\n\nThis operation is useful for obtaining an overview of all workflows within the system, helping\nusers and systems know what workflows are defined, what inputs they require, and how they can\nbe triggered.\n\n[Required scopes](/docs/maestro-api/auth/): `signature`, `aow_manage`\n\n### Use Cases:\n- Listing all available workflows in a system for manual or automated workflow initiation.\n- Reviewing the input requirements for a workflow before triggering it programmatically.\n- Gathering basic metadata about workflows for auditing, logging, or reporting purposes.\n\n### Key Features:\n- **Comprehensive Workflow Overview**: Provides a full list of workflows, giving visibility\n  into all the automated processes available within the Maestro platform.\n- **Input Schema Information**: Each workflow includes its trigger input schema, showing\n  what data must be provided when triggering the workflow.\n- **Metadata for Tracking**: Useful metadata like creation time, last modification date,\n  and user details are included to support tracking and auditing workflows.\n- **Future-Proof**: The operation is designed to be expandable as more workflows are added\n  or the platform grows, ensuring scalability in the workflow management process.\n",
                 "x-ds-methodname": "getWorkflowsList",
                 "tags": [
                     "Workflows"
@@ -114,7 +114,7 @@
             "get": {
                 "operationId": "GetWorkflowTriggerRequirements",
                 "summary": "Retrieve trigger requirements for a specific Maestro workflow",
-                "description": "This operation retrieves the configuration and input requirements necessary to trigger a specific\nMaestro workflow. It provides detailed information about the `trigger_event_type`, such as HTTP\nor other supported types, and specifies the required input schema, including field names, data types,\nand any default values.\n\nThis information is essential for understanding the data and parameters required to initiate the\nworkflow. It enables developers to prepare the necessary inputs and configuration before triggering\nthe workflow instance, ensuring seamless execution and compliance with workflow requirements.\n\n### Use Cases:\n- Identifying the required input fields and their data types to successfully trigger the workflow.\n- Reviewing the trigger configuration for validation and compliance with expected input.\n- Preparing and validating data in advance of triggering the workflow, minimizing runtime errors.\n\n### Key Features:\n- **Detailed Trigger Input Requirements**: Provides an exhaustive schema of required fields,\n  their data types, and optional default values for easy reference and data validation.\n- **Trigger Event Type Information**: Specifies the type of event required to initiate the workflow\n  (e.g., HTTP), helping developers configure their systems to invoke the workflow appropriately.\n- **Configurable for Custom Triggers**: Suitable for custom configurations, enabling flexibility\n  in how workflows can be triggered according to system needs.\n",
+                "description": "This operation retrieves the configuration and input requirements necessary to trigger a specific\nMaestro workflow. It provides detailed information about the `trigger_event_type`, such as HTTP\nor other supported types, and specifies the required input schema, including field names, data types,\nand any default values.\n\nThis information is essential for understanding the data and parameters required to initiate the\nworkflow. It enables developers to prepare the necessary inputs and configuration before triggering\nthe workflow instance, ensuring seamless execution and compliance with workflow requirements.\n\n[Required scopes](/docs/maestro-api/auth/): `signature`, `aow_manage`\n\n### Use Cases:\n- Identifying the required input fields and their data types to successfully trigger the workflow.\n- Reviewing the trigger configuration for validation and compliance with expected input.\n- Preparing and validating data in advance of triggering the workflow, minimizing runtime errors.\n\n### Key Features:\n- **Detailed Trigger Input Requirements**: Provides an exhaustive schema of required fields,\n  their data types, and optional default values for easy reference and data validation.\n- **Trigger Event Type Information**: Specifies the type of event required to initiate the workflow\n  (e.g., HTTP), helping developers configure their systems to invoke the workflow appropriately.\n- **Configurable for Custom Triggers**: Suitable for custom configurations, enabling flexibility\n  in how workflows can be triggered according to system needs.\n",
                 "x-ds-methodname": "getWorkflowTriggerRequirements",
                 "tags": [
                     "Workflows"
@@ -164,7 +164,7 @@
             "post": {
                 "operationId": "TriggerWorkflow",
                 "summary": "Trigger a new instance of a Maestro workflow",
-                "description": "This operation triggers a new instance of a specified Maestro workflow. When invoked,\nthe workflow is started based on the provided input data, and the workflow instance\nbegins executing according to its defined logic and configuration.\n\nThe request requires an `instance_name` and any input data necessary to start the workflow,\nas described by the workflow's `trigger_input_schema`. The `instance_name` is a user-defined\nlabel for tracking the workflow run, while the input data fields should match the schema defined\nin the workflow.\n\nThe operation is event-driven and typically triggered by an external HTTP event or system call,\nallowing for the automatic execution of complex processes that span multiple systems or components.\n\nUpon successful execution, the response returns the unique identifier (`id`) for the newly\ncreated workflow instance, along with a URL (`workflow_instance_url`) that can be used to\ninteract with or track the running instance.\n\n### Use Cases:\n- Automating user registration workflows where input fields like `name` and `email` are provided.\n- Processing financial transactions where details such as `amount` and `currency` are required.\n- Sending notifications based on user interactions in other systems.\n\n### Key Features:\n- **Automated Execution**: Once triggered, the workflow runs until a step requires manual intervention.\n- **Input-Driven**: Workflow execution is based on the provided input data, which is validated\n  against the workflow's input schema.\n- **Real-Time Triggering**: Designed to be invoked as part of an event-driven architecture,\n  allowing for workflows to respond to external events.\n- **Tracking and Interaction**: The response includes a URL that allows users to check the status\n  of the workflow instance or take further actions while it runs.\n",
+                "description": "This operation triggers a new instance of a specified Maestro workflow. When invoked,\nthe workflow is started based on the provided input data, and the workflow instance\nbegins executing according to its defined logic and configuration.\n\nThe request requires an `instance_name` and any input data necessary to start the workflow,\nas described by the workflow's `trigger_input_schema`. The `instance_name` is a user-defined\nlabel for tracking the workflow run, while the input data fields should match the schema defined\nin the workflow.\n\nThe operation is event-driven and typically triggered by an external HTTP event or system call,\nallowing for the automatic execution of complex processes that span multiple systems or components.\n\nUpon successful execution, the response returns the unique identifier (`id`) for the newly\ncreated workflow instance, along with a URL (`workflow_instance_url`) that can be used to\ninteract with or track the running instance.\n\n[Required scopes](/docs/maestro-api/auth/): `signature`, `aow_manage`\n\n### Use Cases:\n- Automating user registration workflows where input fields like `name` and `email` are provided.\n- Processing financial transactions where details such as `amount` and `currency` are required.\n- Sending notifications based on user interactions in other systems.\n\n### Key Features:\n- **Automated Execution**: Once triggered, the workflow runs until a step requires manual intervention.\n- **Input-Driven**: Workflow execution is based on the provided input data, which is validated\n  against the workflow's input schema.\n- **Real-Time Triggering**: Designed to be invoked as part of an event-driven architecture,\n  allowing for workflows to respond to external events.\n- **Tracking and Interaction**: The response includes a URL that allows users to check the status\n  of the workflow instance or take further actions while it runs.\n",
                 "x-ds-methodname": "triggerWorkflow",
                 "tags": [
                     "Workflows"
@@ -215,7 +215,7 @@
             ],
             "get": {
                 "summary": "Retrieve All Workflow Instances",
-                "description": "This operation retrieves a list of all available Maestro workflow instances. It returns basic information\nabout each workflow instance, including its unique identifier (`id`), name, status, timestamps, and\nadditional metadata.\n\nThe response provides key details that help users understand what workflow instances are in progress\nor completed, and the relevant data for each. Each workflow instance entry also includes metadata, such\nas who started it, when it was last modified, and how many steps have been completed.\n\n### Use Cases:\n- Listing all available workflow instances for manual or automated review\n- Monitoring which workflow instances are currently running or have finished\n- Gathering basic metadata about workflow instances for auditing, logging, or reporting purposes\n\n### Key Features:\n- **Comprehensive Instance Overview**: Provides a full list of workflow instances, giving visibility\n  into all ongoing and completed workflows within the Maestro platform\n- **Metadata for Tracking**: Includes helpful metadata like creation time, last modification date,\n  and user details to support audit trails\n- **Scalable and Future-Proof**: Designed to handle growing numbers of workflow instances as the\n  platform scales\n",
+        "description": "This operation retrieves a list of all available Maestro workflow instances. It returns basic information\nabout each workflow instance, including its unique identifier (`id`), name, status, timestamps, and\nadditional metadata.\n\nThe response provides key details that help users understand what workflow instances are in progress\nor completed, and the relevant data for each. Each workflow instance entry also includes metadata, such\nas who started it, when it was last modified, and how many steps have been completed.\n\n[Required scopes](/docs/maestro-api/auth/): `signature`, `aow_manage`\n\n### Use Cases:\n- Listing all available workflow instances for manual or automated review\n- Monitoring which workflow instances are currently running or have finished\n- Gathering basic metadata about workflow instances for auditing, logging, or reporting purposes\n\n### Key Features:\n- **Comprehensive Instance Overview**: Provides a full list of workflow instances, giving visibility\n  into all ongoing and completed workflows within the Maestro platform\n- **Metadata for Tracking**: Includes helpful metadata like creation time, last modification date,\n  and user details to support audit trails\n- **Scalable and Future-Proof**: Designed to handle growing numbers of workflow instances as the\n  platform scales\n",
                 "operationId": "getWorkflowInstancesList",
                 "x-ds-methodname": "getWorkflowInstancesList",
                 "tags": [
@@ -250,7 +250,7 @@
         "/v1/accounts/{accountId}/workflows/{workflowId}/actions/pause": {
             "post": {
                 "summary": "Pause an Active Workflow",
-                "description": "This operation pauses new workflow instances from being created. Any running workflows instances will be unaffected.\n",
+                "description": "This operation pauses new workflow instances from being created. Any running workflows instances will be unaffected.\n\n[Required scopes](/docs/maestro-api/auth/): `signature`, `aow_manage`\n",
                 "operationId": "pauseNewWorkflowInstances",
                 "x-ds-methodname": "pauseNewWorkflowInstances",
                 "tags": [
@@ -294,7 +294,7 @@
         "/v1/accounts/{accountId}/workflows/{workflowId}/actions/resume": {
             "post": {
                 "summary": "Resume a Paused Workflow",
-                "description": "This operation enables new workflow instances to be created\n",
+        "description": "This operation enables new workflow instances to be created.\n\n[Required scopes](/docs/maestro-api/auth/): `signature`, `aow_manage`",
                 "operationId": "resumePausedWorkflow",
                 "x-ds-methodname": "resumePausedWorkflow",
                 "tags": [
@@ -349,7 +349,7 @@
             ],
             "get": {
                 "summary": "Retrieve a Workflow Instance",
-                "description": "This operation retrieves a single Maestro workflow instance by its unique identifier (`id`).\nIt returns the primary details of the workflow instance, including its name, status,\nstarting information, and other metadata.\n\nThe response provides key details that help users understand the current state of the workflow\ninstance, when it was started, and who initiated it. Additional metadata is included to support\nauditing and reporting within the system.\n\n### Use Cases:\n- Getting the details of a specific workflow instance for further processing or review\n- Monitoring the status of a running workflow instance to determine completion or cancellation\n- Accessing metadata for auditing, logging, or reporting on a single workflow instance\n\n### Key Features:\n- **Single Workflow Instance**: Provides direct access to a specific workflow instance by `id`\n- **Detailed Status Information**: Includes the workflow's start and end times, status, and other lifecycle timestamps\n- **Metadata for Tracking**: Useful metadata like who initiated the workflow (`started_by`) and versioning details\n- **Future-Proof**: Designed to be extensible if additional fields or nested information are required over time\n",
+        "description": "This operation retrieves a single Maestro workflow instance by its unique identifier (`id`).\nIt returns the primary details of the workflow instance, including its name, status,\nstarting information, and other metadata.\n\nThe response provides key details that help users understand the current state of the workflow\ninstance, when it was started, and who initiated it. Additional metadata is included to support\nauditing and reporting within the system.\n\n[Required scopes](/docs/maestro-api/auth/): `signature`, `aow_manage`\n\n### Use Cases:\n- Getting the details of a specific workflow instance for further processing or review\n- Monitoring the status of a running workflow instance to determine completion or cancellation\n- Accessing metadata for auditing, logging, or reporting on a single workflow instance\n\n### Key Features:\n- **Single Workflow Instance**: Provides direct access to a specific workflow instance by `id`\n- **Detailed Status Information**: Includes the workflow's start and end times, status, and other lifecycle timestamps\n- **Metadata for Tracking**: Useful metadata like who initiated the workflow (`started_by`) and versioning details\n- **Future-Proof**: Designed to be extensible if additional fields or nested information are required over time\n",
                 "operationId": "getWorkflowInstance",
                 "x-ds-methodname": "getWorkflowInstance",
                 "tags": [
@@ -413,7 +413,7 @@
             ],
             "post": {
                 "summary": "Cancel a Running Workflow Instance",
-                "description": "This operation cancels a running Maestro workflow instance by its unique identifier (`instanceId`).\nOnce canceled, the workflow instance will no longer continue executing any remaining steps.\n\n### Use Cases:\n- Stopping a workflow execution when it is no longer needed or relevant\n- Manually intervening in a workflow to prevent it from reaching completion if conditions change\n\n### Key Features:\n- **Immediate Termination**: Ensures the workflow instance no longer processes subsequent steps\n- **Clear Feedback**: Returns a confirmation message including both the instance and workflow identifiers\n",
+                "description": "This operation cancels a running Maestro workflow instance by its unique identifier (`instanceId`).\nOnce canceled, the workflow instance will no longer continue executing any remaining steps.\n\n[Required scopes](/docs/maestro-api/auth/): `signature`, `aow_manage`\n\n### Use Cases:\n- Stopping a workflow execution when it is no longer needed or relevant\n- Manually intervening in a workflow to prevent it from reaching completion if conditions change\n\n### Key Features:\n- **Immediate Termination**: Ensures the workflow instance no longer processes subsequent steps\n- **Clear Feedback**: Returns a confirmation message including both the instance and workflow identifiers\n",
                 "operationId": "cancelWorkflowInstance",
                 "x-ds-methodname": "cancelWorkflowInstance",
                 "tags": [
@@ -1512,4 +1512,4 @@
             "description": ""
         }
     ]
-}
+}