From 9831b4882f00e58e6a5fe6feae315f82315b2352 Mon Sep 17 00:00:00 2001 From: Junwei Dai Date: Wed, 29 Jan 2025 14:04:44 -0800 Subject: [PATCH 1/3] Edit create workflow and provision workflow page , add wait for time completion param description Signed-off-by: Junwei Dai --- .../api/create-workflow.md | 63 ++++++++++++++++--- .../api/provision-workflow.md | 37 ++++++++++- 2 files changed, 90 insertions(+), 10 deletions(-) diff --git a/_automating-configurations/api/create-workflow.md b/_automating-configurations/api/create-workflow.md index 3feb4672ea..854d6c3632 100644 --- a/_automating-configurations/api/create-workflow.md +++ b/_automating-configurations/api/create-workflow.md @@ -84,6 +84,21 @@ PUT /_plugins/_flow_framework/workflow/?reprovision=true You can add new steps to the workflow but cannot delete them. Only index setting, search pipeline, and ingest pipeline steps can currently be updated. {: .note} +To control how long the request waits for the provisioning and reprovisioning process to complete, use the `wait_for_completion_timeout` parameter. If the operation does not complete within the specified timeout, the response will return the current workflow status while execution continues asynchronously: + +```json +POST /_plugins/_flow_framework/workflow/?provision=true&wait_for_completion_timeout=2s +``` +{% include copy-curl.html %} +```json +PUT /_plugins/_flow_framework/workflow//?reprovision=true&wait_for_completion_timeout=2s +``` +{% include copy-curl.html %} + +The `wait_for_completion_timeout` parameter can only be used when either `provision` or `reprovision` is set to `true` +{: .note} + +For example, the following request provisions a workflow and waits for up to 2 seconds for completion: You can create and provision a workflow using a [workflow template]({{site.url}}{{site.baseurl}}/automating-configurations/workflow-templates/) as follows: ```json @@ -96,14 +111,15 @@ POST /_plugins/_flow_framework/workflow?use_case=&provision=true The following table lists the available query parameters. All query parameters are optional. User-provided parameters are only allowed if the `provision` parameter is set to `true`. -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `provision` | Boolean | Whether to provision the workflow as part of the request. Default is `false`. | -| `update_fields` | Boolean | Whether to update only the fields included in the request body. Default is `false`. | -| `reprovision` | Boolean | Whether to reprovision the entire template if it has already been provisioned. A complete template must be provided in the request body. Default is `false`. | -| `validation` | String | Whether to validate the workflow. Valid values are `all` (validate the template) and `none` (do not validate the template). Default is `all`. | -| `use_case` | String | The name of the [workflow template]({{site.url}}{{site.baseurl}}/automating-configurations/workflow-templates/#supported-workflow-templates) to use when creating the workflow. | -| User-provided substitution expressions | String | Parameters matching substitution expressions in the template. Only allowed if `provision` is set to `true`. Optional. If `provision` is set to `false`, you can pass these parameters in the [Provision Workflow API query parameters]({{site.url}}{{site.baseurl}}/automating-configurations/api/provision-workflow/#query-parameters). | +| Parameter | Data type | Description | +|:---------------------------------------|:----------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `provision` | Boolean | Whether to provision the workflow as part of the request. Default is `false`. | +| `update_fields` | Boolean | Whether to update only the fields included in the request body. Default is `false`. | +| `reprovision` | Boolean | Whether to reprovision the entire template if it has already been provisioned. A complete template must be provided in the request body. Default is `false`. | +| `validation` | String | Whether to validate the workflow. Valid values are `all` (validate the template) and `none` (do not validate the template). Default is `all`. | +| `use_case` | String | The name of the [workflow template]({{site.url}}{{site.baseurl}}/automating-configurations/workflow-templates/#supported-workflow-templates) to use when creating the workflow. | +| `wait_for_completion_timeout` | TimeValue | Specifies the maximum wait time for synchronous provisioning or reprovisioning. If the timeout is exceeded, the request returns the current workflow status while execution continues asynchronously.| +| User-provided substitution expressions | String | Parameters matching substitution expressions in the template. Only allowed if `provision` is set to `true`. Optional. If `provision` is set to `false`, you can pass these parameters in the [Provision Workflow API query parameters]({{site.url}}{{site.baseurl}}/automating-configurations/api/provision-workflow/#query-parameters). | ## Request body fields @@ -291,4 +307,33 @@ OpenSearch responds with the `workflow_id`: } ``` -Once you have created a workflow, you can use other workflow APIs with the `workflow_id`. \ No newline at end of file +Once you have created a workflow, you can use other workflow APIs with the `workflow_id`. + +#### Example Response with wait_for_completion_timeout Enabled + +```json +{ + "workflow_id": "K13IR5QBEpCfUu_-AQdU", + "state": "COMPLETED", + "resources_created": [ + { + "workflow_step_name": "create_connector", + "workflow_step_id": "create_connector_1", + "resource_id": "LF3IR5QBEpCfUu_-Awd_", + "resource_type": "connector_id" + }, + { + "workflow_step_id": "register_model_2", + "workflow_step_name": "register_remote_model", + "resource_id": "L13IR5QBEpCfUu_-BQdI", + "resource_type": "model_id" + }, + { + "workflow_step_name": "deploy_model", + "workflow_step_id": "deploy_model_3", + "resource_id": "L13IR5QBEpCfUu_-BQdI", + "resource_type": "model_id" + } + ] +} +``` \ No newline at end of file diff --git a/_automating-configurations/api/provision-workflow.md b/_automating-configurations/api/provision-workflow.md index c60b6f9892..f4f2acc8a9 100644 --- a/_automating-configurations/api/provision-workflow.md +++ b/_automating-configurations/api/provision-workflow.md @@ -39,6 +39,7 @@ POST /_plugins/_flow_framework/workflow//_provision?=/_provision&wait_for_completion_timeout=2s +``` +{% include copy-curl.html %} + The following request substitutes the expression {% raw %}`${{ openai_key }}`{% endraw %} with the value "12345" using a query parameter: ```json @@ -74,4 +81,32 @@ OpenSearch responds with the same `workflow_id` that was used in the request: } ``` -To obtain the provisioning status, query the [Get Workflow State API]({{site.url}}{{site.baseurl}}/automating-configurations/api/get-workflow-status/). \ No newline at end of file +To obtain the provisioning status, query the [Get Workflow State API]({{site.url}}{{site.baseurl}}/automating-configurations/api/get-workflow-status/). + +#### Example Response with wait_for_completion_timeout Enabled + ```json +{ + "workflow_id": "K13IR5QBEpCfUu_-AQdU", + "state": "COMPLETED", + "resources_created": [ + { + "workflow_step_name": "create_connector", + "workflow_step_id": "create_connector_1", + "resource_id": "LF3IR5QBEpCfUu_-Awd_", + "resource_type": "connector_id" + }, + { + "workflow_step_id": "register_model_2", + "workflow_step_name": "register_remote_model", + "resource_id": "L13IR5QBEpCfUu_-BQdI", + "resource_type": "model_id" + }, + { + "workflow_step_name": "deploy_model", + "workflow_step_id": "deploy_model_3", + "resource_id": "L13IR5QBEpCfUu_-BQdI", + "resource_type": "model_id" + } + ] +} +``` \ No newline at end of file From 5991df84141fb63e4d8d802c09dd6ca15133e21c Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 3 Feb 2025 15:35:29 -0500 Subject: [PATCH 2/3] Doc review Signed-off-by: Fanit Kolchina --- _automating-configurations/api/create-workflow.md | 9 ++++++--- _automating-configurations/api/provision-workflow.md | 8 +++++--- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/_automating-configurations/api/create-workflow.md b/_automating-configurations/api/create-workflow.md index 854d6c3632..6a0dbb7d1b 100644 --- a/_automating-configurations/api/create-workflow.md +++ b/_automating-configurations/api/create-workflow.md @@ -84,17 +84,20 @@ PUT /_plugins/_flow_framework/workflow/?reprovision=true You can add new steps to the workflow but cannot delete them. Only index setting, search pipeline, and ingest pipeline steps can currently be updated. {: .note} -To control how long the request waits for the provisioning and reprovisioning process to complete, use the `wait_for_completion_timeout` parameter. If the operation does not complete within the specified timeout, the response will return the current workflow status while execution continues asynchronously: +To control how long the request waits for the provisioning and reprovisioning process to complete, use the `wait_for_completion_timeout` parameter: ```json POST /_plugins/_flow_framework/workflow/?provision=true&wait_for_completion_timeout=2s ``` {% include copy-curl.html %} + ```json PUT /_plugins/_flow_framework/workflow//?reprovision=true&wait_for_completion_timeout=2s ``` {% include copy-curl.html %} +If the operation does not complete within the specified time, the response returns the current workflow status while execution continues asynchronously. + The `wait_for_completion_timeout` parameter can only be used when either `provision` or `reprovision` is set to `true` {: .note} @@ -118,7 +121,7 @@ The following table lists the available query parameters. All query parameters a | `reprovision` | Boolean | Whether to reprovision the entire template if it has already been provisioned. A complete template must be provided in the request body. Default is `false`. | | `validation` | String | Whether to validate the workflow. Valid values are `all` (validate the template) and `none` (do not validate the template). Default is `all`. | | `use_case` | String | The name of the [workflow template]({{site.url}}{{site.baseurl}}/automating-configurations/workflow-templates/#supported-workflow-templates) to use when creating the workflow. | -| `wait_for_completion_timeout` | TimeValue | Specifies the maximum wait time for synchronous provisioning or reprovisioning. If the timeout is exceeded, the request returns the current workflow status while execution continues asynchronously.| +| `wait_for_completion_timeout` | Time value | Specifies the maximum time to wait for synchronous provisioning or reprovisioning. If this time is exceeded, the request returns the current workflow status while execution continues asynchronously.| | User-provided substitution expressions | String | Parameters matching substitution expressions in the template. Only allowed if `provision` is set to `true`. Optional. If `provision` is set to `false`, you can pass these parameters in the [Provision Workflow API query parameters]({{site.url}}{{site.baseurl}}/automating-configurations/api/provision-workflow/#query-parameters). | ## Request body fields @@ -309,7 +312,7 @@ OpenSearch responds with the `workflow_id`: Once you have created a workflow, you can use other workflow APIs with the `workflow_id`. -#### Example Response with wait_for_completion_timeout Enabled +#### Example Response with wait_for_completion_timeout enabled ```json { diff --git a/_automating-configurations/api/provision-workflow.md b/_automating-configurations/api/provision-workflow.md index f4f2acc8a9..c2232ba4c8 100644 --- a/_automating-configurations/api/provision-workflow.md +++ b/_automating-configurations/api/provision-workflow.md @@ -49,6 +49,7 @@ POST /_plugins/_flow_framework/workflow/8xL8bowB8y25Tqfenm50/_provision {% include copy-curl.html %} The following request performs a synchronous provisioning call, waiting for up to 2 seconds for completion: + ```json POST /_plugins/_flow_framework/workflow//_provision&wait_for_completion_timeout=2s ``` @@ -81,10 +82,11 @@ OpenSearch responds with the same `workflow_id` that was used in the request: } ``` -To obtain the provisioning status, query the [Get Workflow State API]({{site.url}}{{site.baseurl}}/automating-configurations/api/get-workflow-status/). +To obtain the provisioning status, call the [Get Workflow State API]({{site.url}}{{site.baseurl}}/automating-configurations/api/get-workflow-status/). + +#### Example Response with wait_for_completion_timeout enabled -#### Example Response with wait_for_completion_timeout Enabled - ```json +```json { "workflow_id": "K13IR5QBEpCfUu_-AQdU", "state": "COMPLETED", From 4315200bc49ef95dcb8d09e6c40b54e4e428c817 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Mon, 3 Feb 2025 16:25:46 -0500 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _automating-configurations/api/create-workflow.md | 6 +++--- _automating-configurations/api/provision-workflow.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/_automating-configurations/api/create-workflow.md b/_automating-configurations/api/create-workflow.md index 6a0dbb7d1b..f36aa345b4 100644 --- a/_automating-configurations/api/create-workflow.md +++ b/_automating-configurations/api/create-workflow.md @@ -96,7 +96,7 @@ PUT /_plugins/_flow_framework/workflow//?reprovision=true&wait_for_ ``` {% include copy-curl.html %} -If the operation does not complete within the specified time, the response returns the current workflow status while execution continues asynchronously. +If the operation does not complete within the specified amount of time, the response returns the current workflow status while execution continues asynchronously. The `wait_for_completion_timeout` parameter can only be used when either `provision` or `reprovision` is set to `true` {: .note} @@ -121,7 +121,7 @@ The following table lists the available query parameters. All query parameters a | `reprovision` | Boolean | Whether to reprovision the entire template if it has already been provisioned. A complete template must be provided in the request body. Default is `false`. | | `validation` | String | Whether to validate the workflow. Valid values are `all` (validate the template) and `none` (do not validate the template). Default is `all`. | | `use_case` | String | The name of the [workflow template]({{site.url}}{{site.baseurl}}/automating-configurations/workflow-templates/#supported-workflow-templates) to use when creating the workflow. | -| `wait_for_completion_timeout` | Time value | Specifies the maximum time to wait for synchronous provisioning or reprovisioning. If this time is exceeded, the request returns the current workflow status while execution continues asynchronously.| +| `wait_for_completion_timeout` | Time value | Specifies the maximum wait time for synchronous provisioning or reprovisioning. If the timeout is exceeded, the request returns the current workflow status while execution continues asynchronously.| | User-provided substitution expressions | String | Parameters matching substitution expressions in the template. Only allowed if `provision` is set to `true`. Optional. If `provision` is set to `false`, you can pass these parameters in the [Provision Workflow API query parameters]({{site.url}}{{site.baseurl}}/automating-configurations/api/provision-workflow/#query-parameters). | ## Request body fields @@ -312,7 +312,7 @@ OpenSearch responds with the `workflow_id`: Once you have created a workflow, you can use other workflow APIs with the `workflow_id`. -#### Example Response with wait_for_completion_timeout enabled +#### Example response with wait_for_completion_timeout enabled ```json { diff --git a/_automating-configurations/api/provision-workflow.md b/_automating-configurations/api/provision-workflow.md index c2232ba4c8..d9d90ce7f3 100644 --- a/_automating-configurations/api/provision-workflow.md +++ b/_automating-configurations/api/provision-workflow.md @@ -84,7 +84,7 @@ OpenSearch responds with the same `workflow_id` that was used in the request: To obtain the provisioning status, call the [Get Workflow State API]({{site.url}}{{site.baseurl}}/automating-configurations/api/get-workflow-status/). -#### Example Response with wait_for_completion_timeout enabled +#### Example response with wait_for_completion_timeout enabled ```json {