From 3a7bbeb7f1b29f4b45cb7bb0049090ba97c7e121 Mon Sep 17 00:00:00 2001 From: Junwei Dai <59641585+junweid62@users.noreply.github.com> Date: Mon, 3 Feb 2025 13:31:40 -0800 Subject: [PATCH] Add Documentation for `wait_for_completion_timeout` Parameter (#9138) * Edit create workflow and provision workflow page , add wait for time completion param description Signed-off-by: Junwei Dai * Doc review Signed-off-by: Fanit Kolchina * Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --------- Signed-off-by: Junwei Dai Signed-off-by: Fanit Kolchina Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Junwei Dai Co-authored-by: Fanit Kolchina Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Nathan Bower --- .../api/create-workflow.md | 66 ++++++++++++++++--- .../api/provision-workflow.md | 39 ++++++++++- 2 files changed, 95 insertions(+), 10 deletions(-) diff --git a/_automating-configurations/api/create-workflow.md b/_automating-configurations/api/create-workflow.md index 3feb4672ea..f36aa345b4 100644 --- a/_automating-configurations/api/create-workflow.md +++ b/_automating-configurations/api/create-workflow.md @@ -84,6 +84,24 @@ 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: + +```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 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} + +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 +114,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` | 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 @@ -291,4 +310,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..d9d90ce7f3 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 +82,33 @@ 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, call 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