Skip to content

Commit

Permalink
Add Documentation for wait_for_completion_timeout Parameter (#9138)
Browse files Browse the repository at this point in the history 
* Edit create workflow and provision workflow page , add wait for time completion param description

Signed-off-by: Junwei Dai <[email protected]>

* Doc review

Signed-off-by: Fanit Kolchina <[email protected]>

* Apply suggestions from code review

Co-authored-by: Nathan Bower <[email protected]>
Signed-off-by: kolchfa-aws <[email protected]>

---------

Signed-off-by: Junwei Dai <[email protected]>
Signed-off-by: Fanit Kolchina <[email protected]>
Signed-off-by: kolchfa-aws <[email protected]>
Co-authored-by: Junwei Dai <[email protected]>
Co-authored-by: Fanit Kolchina <[email protected]>
Co-authored-by: kolchfa-aws <[email protected]>
Co-authored-by: Nathan Bower <[email protected]>
  • Loading branch information
@junweid62 @kolchfa-aws @natebower
5 people authored Feb 3, 2025
1 parent 1eb2407 commit 3a7bbeb
Show file tree
Hide file tree
Showing 2 changed files with 95 additions and 10 deletions.
66 changes: 57 additions & 9 deletions _automating-configurations/api/create-workflow.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,24 @@ PUT /_plugins/_flow_framework/workflow/<workflow_id>?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/<workflow_id>/?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
Expand All @@ -96,14 +114,15 @@ POST /_plugins/_flow_framework/workflow?use_case=<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

Expand Down Expand Up @@ -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`.
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"
}
]
}
```
39 changes: 38 additions & 1 deletion _automating-configurations/api/provision-workflow.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ POST /_plugins/_flow_framework/workflow/<workflow_id>/_provision?<parameter>=<va
| Parameter | Data type | Description |
| :--- | :--- | :--- |
| User-provided substitution expressions | String | Parameters matching substitution expressions in the template. Optional. |
| `wait_for_completion_timeout` | TimeValue | Specifies the maximum wait time for synchronous provisioning. If the timeout is exceeded, the request returns the current workflow status while execution continues asynchronously.|

#### Example requests

Expand All @@ -47,6 +48,13 @@ 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/<workflow_id>/_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
Expand Down Expand Up @@ -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/).
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"
}
]
}
```

0 comments on commit 3a7bbeb

Please sign in to comment.