---
title: "Workflow DSL"
source: "https://docs.vertesiahq.com/workflows/workflow-dsl"
markdown: "https://docs.vertesiahq.com/llms/workflows/workflow-dsl.md"
---

# Workflow DSL

The Vertesia Platform uses a DSL to define workflows. The DSL is a JSON object that describes the steps of the workflow. Each step can be either an activity or a child workflow.

## Activities

The following activities are available:

| Activity Name | Description | Parameters | Output |
|---|---|---|---|
| **extractText** | Extracts text from a document. | `document`: The document to extract text from. | `text`: The extracted text. |
| **generateText** | Generates text using a prompt template. | `prompt`: The prompt template to use. `data`: The data to pass to the prompt template. | `text`: The generated text. |
| **translateText** | Translates text from one language to another. | `text`: The text to translate. `targetLanguage`: The target language. | `translatedText`: The translated text. |
| **summarizeText** | Summarizes text. | `text`: The text to summarize. | `summary`: The summarized text. |
| **analyzeSentiment** | Analyzes the sentiment of text. | `text`: The text to analyze. | `sentiment`: The sentiment of the text. |
| **classifyText** | Classifies text into categories. | `text`: The text to classify. `categories`: The categories to classify into. | `category`: The category of the text. |
| **extractEntities** | Extracts entities from text. | `text`: The text to extract entities from. | `entities`: The extracted entities. |
| **generateEmbeddings** | Generates embeddings for text. | `text`: The text to generate embeddings for. | `embeddings`: The generated embeddings. |
| **searchEmbeddings** | Searches for similar text using embeddings. | `embeddings`: The embeddings to search for. | `results`: The search results. |
| **createDocument** | Creates a new document. | `type`: The type of the document. `properties`: The properties of the document. | `document`: The created document. |
| **updateDocument** | Updates an existing document. | `document`: The document to update. `properties`: The properties to update. | `document`: The updated document. |
| **deleteDocument** | Deletes an existing document. | `document`: The document to delete. | |
| **executeInteraction** | Executes an existing interaction. | `interaction`: The interaction to execute. `data`: The data to pass to the interaction. | `result`: The result of the interaction. |
| **runJavascriptCode** | Runs JavaScript code. | `code`: The JavaScript code to run. | `result`: The result of the code execution. |
| **sleep** | Pauses the workflow for a specified amount of time. | `duration`: The duration to pause for. | |
| **log** | Logs a message to the console. | `message`: The message to log. | |

### Child Workflows

Child workflows are used to execute another workflow as a step in the current workflow. The `name` property specifies the endpoint of the child workflow to execute. The `async` property specifies whether or not to wait for the child workflow to finish before continuing the current workflow.

### Example DSL Workflow

```json
{
  "name": "My Workflow",
  "description": "This is my workflow.",
  "vars": {
    "myVariable": "Hello World!"
  },
  "steps": [
    {
      "type": "activity",
      "name": "log",
      "params": {
        "message": "The value of myVariable is: ${myVariable}"
      }
    },
    {
      "type": "workflow",
      "name": "My Child Workflow",
      "async": true,
      "output": "childWorkflowResult"
    }
  ]
}
```

### DSL Variables

The DSL supports variables that can be used to store data and pass it between steps. Variables are defined in the `vars` property of the workflow. The value of a variable can be a literal value or a reference to another variable. References to variables are enclosed in `${}`. For example, the following DSL defines a variable named `myVariable` with the value "Hello World!":

```json
{
  "vars": {
    "myVariable": "Hello World!"
  }
}
```

The value of `myVariable` can then be referenced in other parts of the DSL using `${myVariable}`. For example, the following DSL logs the value of `myVariable` to the console:

```json
{
  "steps": [
    {
      "type": "activity",
      "name": "log",
      "params": {
        "message": "The value of myVariable is: ${myVariable}"
      }
    }
  ]
}
```

### DSL Conditions

The DSL supports conditions that can be used to control the flow of the workflow. Conditions are defined in the `condition` property of a step. The value of a condition is a JSON object that describes the condition. The following operators are supported:

| Operator | Description |
|---|---|
| `$eq` | Equal to |
| `$ne` | Not equal to |
| `$gt` | Greater than |
| `$gte` | Greater than or equal to |
| `$lt` | Less than |
| `$lte` | Less than or equal to |
| `$in` | In array |
| `$nin` | Not in array |
| `$regexp` | Matches regular expression |

For example, the following DSL defines a step that only executes if the value of the variable `myVariable` is equal to "Hello World!":

```json
{
  "steps": [
    {
      "type": "activity",
      "name": "log",
      "condition": {
        "$eq": {
          "myVariable": "Hello World!"
        }
      },
      "params": {
        "message": "The value of myVariable is: ${myVariable}"
      }
    }
  ]
}
```

### DSL Fetch

The DSL supports fetching data from external sources during the workflow execution. The `fetch` property of a step is used to define the data to fetch. The value of the `fetch` property is a JSON object that describes the data to fetch. The following properties are supported:

| Property | Description |
|---|---|
| `type` | The type of data to fetch. |
| `source` | The source of the data. |
| `query` | The query to use to fetch the data. |
| `select` | The fields to select from the fetched data. |
| `limit` | The maximum number of results to fetch. |
| `on_not_found` | How to handle not found objects. |

For example, the following DSL defines a step that fetches a document from the store:

```json
{
  "steps": [
    {
      "type": "activity",
      "name": "fetchDocument",
      "fetch": {
        "type": "document",
        "query": {
          "id": "${documentId}"
        }
      },
      "output": "document"
    }
  ]
}
```

### DSL Projection

The DSL supports projecting data from the result of an activity. The `projection` property of a step is used to define the data to project. The value of the `projection` property is a JSON object that describes the data to project. The following operators are supported:

| Operator | Description |
|---|---|
| `$include` | Include the specified fields. |
| `$exclude` | Exclude the specified fields. |

For example, the following DSL defines a step that projects the `name` and `description` fields from the result of the `fetchDocument` activity:

```json
{
  "steps": [
    {
      "type": "activity",
      "name": "fetchDocument",
      "fetch": {
        "type": "document",
        "query": {
          "id": "${documentId}"
        }
      },
      "output": "document"
    },
    {
      "type": "activity",
      "name": "projectDocument",
      "params": {
        "document": "${document}"
      },
      "projection": {
        "$include": [
          "name",
          "description"
        ]
      },
      "output": "projectedDocument"
    }
  ]
}
```