Create or update a workflow

Creating a workflow adds the content of a workflow template to the flow framework system index. You can provide workflows in JSON format (by specifying Content-Type: application/json) or YAML format (by specifying Content-Type: application/yaml). By default, the workflow is validated to help identify invalid configurations, including:

  • Workflow steps requiring an OpenSearch plugin that is not installed.
  • Workflow steps relying on previous node input that is provided by those steps.
  • Workflow step fields with invalid values.
  • Workflow graph (node/edge) configurations containing cycles or with duplicate IDs.

To obtain the validation template for workflow steps, call the Get Workflow Steps API.

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: '$'. 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 by using the Provision Workflow API or by 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. You can specify the update_fields parameter to update specific fields.

You can only update a complete workflow if it has not yet been provisioned.

Path and HTTP methods

  1. POST /_plugins/_flow_framework/workflow
  2. PUT /_plugins/_flow_framework/workflow/<workflow_id>

Path parameters

The following table lists the available path parameters.

ParameterData typeDescription
workflow_idStringThe ID of the workflow to be updated. Required for the PUT method.

Query parameters

Workflows are normally created and provisioned in separate steps. However, once you have thoroughly tested the workflow, you can combine the create and provision steps by including the provision query parameter:

  1. POST /_plugins/_flow_framework/workflow?provision=true

copy

When set to true, the Provision Workflow API is executed immediately following creation.

By default, workflows are validated when they are created to ensure that the syntax is valid and that the graph does not contain cycles. This behavior can be controlled with the validation query parameter. If validation is set to all, OpenSearch performs a complete template validation. Any other value of the validation parameter suppresses validation, allowing an incomplete/work-in-progress template to be saved. To disable template validation, set validation to none:

  1. POST /_plugins/_flow_framework/workflow?validation=none

copy

You cannot update a full workflow once it has been provisioned, but you can update fields other than the workflows field, such as name and description:

  1. PUT /_plugins/_flow_framework/workflow/<workflow_id>?update_fields=true
  2. {
  3.   "name": "new-template-name",
  4.   "description": "A new description for the existing template"
  5. }

copy

You cannot specify both the provision and update_fields parameters at the same time.

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.

ParameterData typeDescription
provisionBooleanWhether to provision the workflow as part of the request. Default is false.
update_fieldsBooleanWhether to update only the fields included in the request body. Default is false.
validationStringWhether to validate the workflow. Valid values are all (validate the template) and none (do not validate the template). Default is all.
User-provided substitution expressionsStringParameters 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.

Request fields

The following table lists the available request fields.

FieldData typeRequired/OptionalDescription
nameStringRequiredThe name of the workflow.
descriptionStringOptionalA description of the workflow.
use_caseStringOptionalA use case, which can be used with the Search Workflow API to find related workflows. In the future, OpenSearch may provide some standard use cases to ease categorization, but currently you can use this field to specify custom values.
versionObjectOptionalA key-value map with two fields: template, which identifies the template version, and compatibility, which identifies a list of minimum required OpenSearch versions.
workflowsObjectOptionalA map of workflows. Presently, only the provision key is supported. The value for the workflow key is a key-value map that includes fields for user_params and lists of nodes and edges.

Example request: Register and deploy an externally hosted model (YAML)

To provide a template in YAML format, specify Content-Type: application/yaml in the request header:

  1. curl -XPOST "http://localhost:9200/_plugins/_flow_framework/workflow" -H 'Content-Type: application/yaml'

YAML templates permit comments.

The following is an example YAML template for registering and deploying an externally hosted model:

  1. # This name is required
  2. name: createconnector-registerremotemodel-deploymodel
  3. # Other fields are optional but useful
  4. description: This template creates a connector to a remote model, registers it, and
  5.   deploys that model
  6. # Other templates with a similar use case can be searched
  7. use_case: REMOTE_MODEL_DEPLOYMENT
  8. version:
  9.   # Templates may be versioned by their authors
  10.   template: 1.0.0
  11.   # Compatibility with OpenSearch 2.12.0 and higher and 3.0.0 and higher
  12.   compatibility:
  13.   - 2.12.0
  14.   - 3.0.0
  15. # One or more workflows can be included, presently only provision is supported
  16. workflows:
  17.   provision:
  18.     # These nodes are the workflow steps corresponding to ML Commons APIs
  19.     nodes:
  20.     # This ID must be unique to this workflow
  21.     - id: create_connector_1
  22.       # There may be multiple steps with the same type
  23.       type: create_connector
  24.       # These inputs match the Create Connector API body
  25.       user_inputs:
  26.         name: OpenAI Chat Connector
  27.         description: The connector to public OpenAI model service for GPT 3.5
  28.         version: '1'
  29.         protocol: http
  30.         parameters:
  31.           endpoint: api.openai.com
  32.           model: gpt-3.5-turbo
  33.         credential:
  34.           openAI_key: '12345'
  35.         actions:
  36.         - action_type: predict
  37.           method: POST
  38.           url: https://${parameters.endpoint}/v1/chat/completions
  39.     # This ID must be unique to this workflow
  40.     - id: register_model_2
  41.       type: register_remote_model
  42.       # This step needs the connector_id produced as an output of the previous step
  43.       previous_node_inputs:
  44.         create_connector_1: connector_id
  45.       # These inputs match the Register Model API body
  46.       user_inputs:
  47.         name: openAI-gpt-3.5-turbo
  48.         function_name: remote
  49.         description: test model
  50.     # This ID must be unique to this workflow
  51.     - id: deploy_model_3
  52.       type: deploy_model
  53.       # This step needs the model_id produced as an output of the previous step
  54.       previous_node_inputs:
  55.         register_model_2: model_id
  56.     # Since the nodes include previous_node_inputs these are optional to define
  57.     # They will be added automatically and included in the stored template
  58.     # Additional edges may also be added here if required for sequencing
  59.     edges:
  60.     - source: create_connector_1
  61.       dest: register_model_2
  62.     - source: register_model_2
  63.       dest: deploy_model_3

copy

Example request: Register and deploy a remote model (JSON)

To provide a template in JSON format, specify Content-Type: application/json in the request header:

  1. curl -XPOST "http://localhost:9200/_plugins/_flow_framework/workflow" -H 'Content-Type: application/json'

The following JSON template is equivalent to the YAML template provided in the previous section:

  1. {
  2.   "name": "createconnector-registerremotemodel-deploymodel",
  3.   "description": "This template creates a connector to a remote model, registers it, and deploys that model",
  4.   "use_case": "REMOTE_MODEL_DEPLOYMENT",
  5.   "version": {
  6.     "template": "1.0.0",
  7.     "compatibility": [
  8.       "2.12.0",
  9.       "3.0.0"
  10.     ]
  11.   },
  12.   "workflows": {
  13.     "provision": {
  14.       "nodes": [
  15.         {
  16.           "id": "create_connector_1",
  17.           "type": "create_connector",
  18.           "user_inputs": {
  19.             "name": "OpenAI Chat Connector",
  20.             "description": "The connector to public OpenAI model service for GPT 3.5",
  21.             "version": "1",
  22.             "protocol": "http",
  23.             "parameters": {
  24.               "endpoint": "api.openai.com",
  25.               "model": "gpt-3.5-turbo"
  26.             },
  27.             "credential": {
  28.               "openAI_key": "12345"
  29.             },
  30.             "actions": [
  31.               {
  32.                 "action_type": "predict",
  33.                 "method": "POST",
  34.                 "url": "https://${parameters.endpoint}/v1/chat/completions"
  35.               }
  36.             ]
  37.           }
  38.         },
  39.         {
  40.           "id": "register_model_2",
  41.           "type": "register_remote_model",
  42.           "previous_node_inputs": {
  43.             "create_connector_1": "connector_id"
  44.           },
  45.           "user_inputs": {
  46.             "name": "openAI-gpt-3.5-turbo",
  47.             "function_name": "remote",
  48.             "description": "test model"
  49.           }
  50.         },
  51.         {
  52.           "id": "deploy_model_3",
  53.           "type": "deploy_model",
  54.           "previous_node_inputs": {
  55.             "register_model_2": "model_id"
  56.           }
  57.         }
  58.       ],
  59.       "edges": [
  60.         {
  61.           "source": "create_connector_1",
  62.           "dest": "register_model_2"
  63.         },
  64.         {
  65.           "source": "register_model_2",
  66.           "dest": "deploy_model_3"
  67.         }
  68.       ]
  69.     }
  70.   }
  71. }

copy

Example response

OpenSearch responds with the workflow_id:

  1. {
  2.   "workflow_id" : "8xL8bowB8y25Tqfenm50"
  3. }

Once you have created a workflow, you can use other workflow APIs with the workflow_id.