Add documentation for parameter substitution when provisioning workfl…

…ows (#6547) * Add documentation for parameter substitution when provisioning workflows Signed-off-by: Daniel Widdis <[email protected]> * fix typo Signed-off-by: Daniel Widdis <[email protected]> * Update _automating-configurations/api/create-workflow.md Co-authored-by: kolchfa-aws <[email protected]> Signed-off-by: Daniel Widdis <[email protected]> * Update _automating-configurations/api/provision-workflow.md Co-authored-by: kolchfa-aws <[email protected]> Signed-off-by: Daniel Widdis <[email protected]> * Update _automating-configurations/api/provision-workflow.md Co-authored-by: kolchfa-aws <[email protected]> Signed-off-by: Daniel Widdis <[email protected]> * Update _automating-configurations/api/provision-workflow.md Co-authored-by: kolchfa-aws <[email protected]> Signed-off-by: Daniel Widdis <[email protected]> * Update _automating-configurations/api/provision-workflow.md Co-authored-by: kolchfa-aws <[email protected]> Signed-off-by: Daniel Widdis <[email protected]> * Clarify user-provided parameters in create workflow API Signed-off-by: Daniel Widdis <[email protected]> * Clarify user-provided parameters in provision workflow API Signed-off-by: Daniel Widdis <[email protected]> * Add link to provision workflow from create workflow Signed-off-by: Fanit Kolchina <[email protected]> * Update _automating-configurations/api/provision-workflow.md Signed-off-by: kolchfa-aws <[email protected]> --------- Signed-off-by: Daniel Widdis <[email protected]> Signed-off-by: Fanit Kolchina <[email protected]> Signed-off-by: kolchfa-aws <[email protected]> Co-authored-by: kolchfa-aws <[email protected]> Co-authored-by: Fanit Kolchina <[email protected]>
opensearch-project · Mar 25, 2024 · b191690 · b191690
1 parent 73202ea
commit b191690
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 2 deletions.
diff --git a/_automating-configurations/api/create-workflow.md b/_automating-configurations/api/create-workflow.md
@@ -16,6 +16,8 @@ Creating a workflow adds the content of a workflow template to the flow framewor
 
 To obtain the validation template for workflow steps, call the [Get Workflow Steps API]({{site.url}}{{site.baseurl}}/automating-configurations/api/get-workflow-steps/).
 
+You can include placeholder expressions in the value of workflow step fields. For example, you can specify a credential field in a template as `openAI_key: '${{ openai_key }}'`. The expression will be substituted with the user-provided value during provisioning, using the format `${{ <value> }}`. You can pass the actual key as a parameter using the [Provision Workflow API]({{site.url}}{{site.baseurl}}/automating-configurations/api/provision-workflow/) or using this API with the `provision` parameter set to `true`.
+
 Once a workflow is created, provide its `workflow_id` to other APIs.
 
 The `POST` method creates a new workflow. The `PUT` method updates an existing workflow. 
@@ -56,12 +58,13 @@ POST /_plugins/_flow_framework/workflow?validation=none
 ```
 {% include copy-curl.html %}
 
-The following table lists the available query parameters. All query parameters are optional.
+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`. |
 | `validation` | String | Whether to validate the workflow. Valid values are `all` (validate the template) and `none` (do not validate the template). Default is `all`. |
+| 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 fields
 

diff --git a/_automating-configurations/api/provision-workflow.md b/_automating-configurations/api/provision-workflow.md
@@ -28,13 +28,42 @@ The following table lists the available path parameters.
 | :--- | :--- | :--- |
 | `workflow_id` | String | The ID of the workflow to be provisioned. Required. |
 
-#### Example request
+## Query parameters
+
+If you have included a substitution expression in the template, you may pass it as a query parameter or as a string value of a request body field. For example, if you specified a credential field in a template as `openAI_key: '${{ openai_key }}'`, then you can include the `openai_key` parameter as a query parameter or body field so it can be substituted during provisioning. For example, the following request provides a query parameter:
+
+```json
+POST /_plugins/_flow_framework/workflow/<workflow_id>/_provision?<parameter>=<value>
+```
+
+| Parameter | Data type | Description |
+| :--- | :--- | :--- |
+| User-provided substitution expressions | String | Parameters matching substitution expressions in the template. Optional. |
+
+#### Example requests
 
 ```json
 POST /_plugins/_flow_framework/workflow/8xL8bowB8y25Tqfenm50/_provision
 ```
 {% include copy-curl.html %}
 
+The following request substitutes the expression `${{ openai_key }}` with the value "12345" using a query parameter:
+
+```json
+POST /_plugins/_flow_framework/workflow/8xL8bowB8y25Tqfenm50/_provision?openai_key=12345
+```
+{% include copy-curl.html %}
+
+The following request substitutes the expression `${{ openai_key }}` with the value "12345" using the request body:
+
+```json
+POST /_plugins/_flow_framework/workflow/8xL8bowB8y25Tqfenm50/_provision
+{
+  "openai_key" : "12345"
+}
+```
+{% include copy-curl.html %}
+
 #### Example response
 
 OpenSearch responds with the same `workflow_id` that was used in the request: