# Utilities

<!-- Generated by tools/catalogue/generate.py from flow.service.workflow 5.0.0-beta.39. Don't edit by hand. -->

# Utilities

The Utilities category has 7 tasks. Each entry shows the task's latest revision, the one the palette adds. See [Reading an entry](https://www.useboomerang.io/docs/flow/main/catalogue/overview#reading-an-entry).

## Execute Advanced HTTP Call

Execute an Advanced HTTP Call

- **Slug:** `execute-advanced-http-call`
- **Type:** `template`
- **Revision:** 4
- **Image:** Default task image.

> [!WARNING]
> Every revision sends no request and ends `succeeded` on `boomerangio/task-flow:3.3.0`, the default task image, so a later task that reads `response` or `statusCode` gets nothing. Fixed in task-flow 3.4.0: set Default Image Path to `boomerangio/task-flow:3.4.0`. See [The HTTP Call tasks do nothing](https://www.useboomerang.io/docs/flow/main/introduction/known-issues#the-http-call-tasks-do-nothing).

**Parameters**

| Label | Name | Type | Required | Default | Helper text |
| --- | --- | --- | --- | --- | --- |
| URL | `url` | URL | No |  |  |
| Method | `method` | Select | No |  |  |
| Headers | `header` | Text Area | No |  | Headers to add to the request, such as Authorization |
| Content Type | `contentType` | Text | No |  |  |
| Body | `body` | Text Editor | No |  |  |
| Allow Untrusted SSL Certs | `allowUntrustedCerts` | Boolean | No |  |  |
| Response File Path | `outputFilePath` | Text | No |  | File path to store the output response |
| HTTP response codes for successful execution | `successcodes` | Text | No | `1xx,2xx` |  |
| HTTP response codes for failure | `errorcodes` | Text | No |  | HTTP response codes which marks the call as failed |
| HTTP response codes for execution retry | `retrycodes` | Text | No | `502,503` | HTTP response codes for retry |
| Number of milliseconds to wait until the next retry | `retrydelay` | Number | No |  | Cool down between retries in millis (100, 300000) |
| Number of retries | `retrynumber` | Number | No | `3` | Number of retries to be attempted, between (1, 9) |

**Results**

| Name | Description |
| --- | --- |
| `response` | HTTP execution response content |
| `statusCode` | The received HTTP status code |

### Example

> [!WARNING]
> This example works from task-flow 3.4.0: set Default Image Path to `boomerangio/task-flow:3.4.0`. On `boomerangio/task-flow:3.3.0`, the default task image, the task sends no request: see the warning above.

Record a deployment with an internal API, and retry while the service restarts.

| Field | Value |
| --- | --- |
| **Task name** | `record-deploy` |
| **URL** | `https://deploy.example.com/api/deployments` |
| **Method** | `POST` |
| **Headers** | `Authorization: Bearer $(workspace.params.deploy-token)` |
| **Content Type** | `application/json` |
| **Body** | The JSON below |
| **HTTP response codes for execution retry** | Leave `502,503` |
| **Number of retries** | Leave `3` |
| **Number of milliseconds to wait until the next retry** | `2000` |

**Body**

```json
{"service": "$(params.service)", "version": "$(params.version)"}
```

The task returns:

| Result | Value |
| --- | --- |
| `statusCode` | The status received, such as `201` |
| `response` | The response body as text, such as `{"id":"d-1042"}`, when it's 3,000 bytes or less |

A 502 or 503 is retried up to 3 times, 2 seconds apart. Any 2xx succeeds. Any other status not in **HTTP response codes for successful execution** fails the task, with `statusCode`, and `response` when it fits, still set. **Headers** takes one `Name: value` per line, and only the names reach the log. For a larger response, set **Response File Path** to an absolute path or one relative to `/workspace`; `response` is then empty.

### Common problems

| Symptom | Cause | Fix |
| --- | --- | --- |
| The task succeeds at once, and `statusCode` and `response` are empty | On `boomerangio/task-flow:3.3.0`, the default task image, the HTTP command is switched off. | Set Default Image Path to `boomerangio/task-flow:3.4.0`, or call the API with `curl --fail` in **Execute Shell**. See [The HTTP Call tasks do nothing](https://www.useboomerang.io/docs/flow/main/introduction/known-issues#the-http-call-tasks-do-nothing). |
| The task fails, saying the response is more than a task result can carry | The body is over 3,000 bytes, and **Response File Path** is blank. | Set **Response File Path**, and read the file in a later task. |
| A `301` or `302` fails the task | The task doesn't follow redirects. | Call the final URL, or add the code to **HTTP response codes for successful execution**. |
| The task fails before sending, saying the body isn't valid JSON | **Content Type** is a JSON type, and **Body** isn't valid JSON, often because a reference inserted a quote. | Correct the body. The task sends it as written. |

## Execute Basic HTTP Call

Execute a Basic HTTP Call

- **Slug:** `execute-basic-http-call`
- **Type:** `template`
- **Revision:** 1
- **Image:** Default task image.

> [!WARNING]
> Every revision sends no request and ends `succeeded` on `boomerangio/task-flow:3.3.0`, the default task image, so a later task that reads `response` or `statusCode` gets nothing. Fixed in task-flow 3.4.0: set Default Image Path to `boomerangio/task-flow:3.4.0`. See [The HTTP Call tasks do nothing](https://www.useboomerang.io/docs/flow/main/introduction/known-issues#the-http-call-tasks-do-nothing).

**Parameters**

| Label | Name | Type | Required | Default | Helper text |
| --- | --- | --- | --- | --- | --- |
| URL | `url` | URL | No |  |  |
| Method | `method` | Select | No |  |  |
| Headers | `header` | Text Area | No |  | Headers to add to the request, such as Authorizati |
| Content Type | `contentType` | Text | No |  |  |
| Body | `body` | Text Editor | No |  |  |
| Allow Untrusted SSL Certs | `allowUntrustedCerts` | Boolean | No | `false` |  |
| Response File Path | `outputFilePath` | Text | No |  | File path to store the output response |

**Results**

| Name | Description |
| --- | --- |
| `response` | HTTP execution response content |
| `statusCode` | The received HTTP status code |

## Execute Shell

Execute a shell script

- **Slug:** `execute-shell`
- **Type:** `script`
- **Revision:** 2
- **Image:** Default task image.

**Parameters**

| Label | Name | Type | Required | Default | Helper text |
| --- | --- | --- | --- | --- | --- |
| Directory Path | `path` | Text | No |  |  |
| Shell Interpreter | `shell` | Text | No |  |  |
| Shell Script | `script` | Text Editor - Shell | Yes |  |  |

No results.

### Example

Make a file name from the workflow parameter `version` and return it as the result `filename`, for a later task to read. This is the `build` task in [Pass results between tasks with an approval](https://www.useboomerang.io/docs/flow/main/tutorials/pass-results-with-an-approval).

| Field | Value |
| --- | --- |
| **Task name** | `build` |
| **Directory Path** | Blank, so the script runs in `/data` |
| **Shell Interpreter** | Blank, so BusyBox `sh` runs the script |
| **Shell Script** | The script below |
| **Result Parameters** | **Name** `filename`, **Description** `The file the build made` |

**Shell Script**

```sh
filename="my-app-$(params.version).tar.gz"
echo "Built $filename"
if [ -d "$RESULTS_PATH" ]; then
  printf '%s' "$filename" > "$RESULTS_PATH/filename"
else
  printf '{"filename":"%s"}' "$filename" > "$RESULTS_PATH"
fi
```

The task returns:

| Result | Value |
| --- | --- |
| `filename` | `my-app-1.4.2.tar.gz`, for a run started with `version` `1.4.2` |

Flow replaces `$(params.version)` before the script runs, and a later task reads the result as `$(tasks.build.results.filename)`. `RESULTS_PATH` is a directory on the `tekton` executor and a file on `kube-jobs`, and the `if` covers both. The default task image has `bash`, `curl`, `sed`, `grep`, `tar` and Node.js, but not `jq`. To use `bash` syntax, set **Shell Interpreter** to `bash`.

### Common problems

| Symptom | Cause | Fix |
| --- | --- | --- |
| A later task reads an empty value from the result | The script didn't write the result to `$RESULTS_PATH`, or the node doesn't declare it under **Result Parameters**. Flow keeps only declared results. | Declare each result on the node, and write it as the example does. See [Return results](https://www.useboomerang.io/docs/flow/main/guides/tasks#return-results). |
| A later task can't find a file the script wrote | **Directory Path** is blank, so the script ran in `/data`, scratch space that only this task sees. | Turn on **Shared workspace for each run** under **Configure › Workspace**, then set **Directory Path** to `/workspace`, or write to paths under it. |
| The task fails with `No such file or directory: /workspace/` | On `boomerangio/task-flow:3.3.0`, **Directory Path** must be an absolute path that exists, with no trailing slash. A relative path, a trailing `/`, or `/workspace` without the run workspace each fail. From task-flow 3.4.0, a trailing slash or a path relative to `/workspace` works. | Enter an absolute path such as `/workspace`, or move to `boomerangio/task-flow:3.4.0`. |
| The task succeeds although a command in the script failed | Only the exit status of the script's last command counts. | Start the script with `set -e`, so the first command that fails ends the task **Failed**. |

## File JSONPath To Parameter

Takes the first value from the file content returned by a valid JSONPath expression and sets as an output property

- **Slug:** `file-jsonpath-to-parameter`
- **Type:** `template`
- **Revision:** 2
- **Image:** Default task image.

**Parameters**

| Label | Name | Type | Required | Default | Helper text |
| --- | --- | --- | --- | --- | --- |
| File Path | `filePath` | Text | Yes |  | File content to query |
| Query Expression | `query` | Text | No |  | A valid JSON path expression |

**Results**

| Name | Description |
| --- | --- |
| `evaluation` | The value based on the applied expression |

## JSONPath To Parameter

Takes the first value returned by a valid JSONPath expression and sets as an output property

- **Slug:** `jsonpath-to-parameter`
- **Type:** `template`
- **Revision:** 3
- **Image:** Default task image.

**Parameters**

| Label | Name | Type | Required | Default | Helper text |
| --- | --- | --- | --- | --- | --- |
| Json | `json` | Text Area | No |  | Json object to query |
| Query Expression | `query` | Text | No |  | A valid JSON path expression |

**Results**

| Name | Description |
| --- | --- |
| `evaluation` | The value based on the applied expression |

### Example

An earlier task named `scan` returns a JSON report in its result `report`, such as `{"findings":[{"id":"CVE-2026-1234","severity":"high"}],"total":1}`. Pick out the first finding's severity, for a later task to act on.

| Field | Value |
| --- | --- |
| **Task name** | `severity` |
| **Json** | `$(tasks.scan.results.report)` |
| **Query Expression** | `$.findings[0].severity` |

The task returns:

| Result | Value |
| --- | --- |
| `evaluation` | `high` |

The task returns the first value the expression matches. An array or object comes back as JSON text, and a number as its digits. For a plain path you don't need this task: a reference can follow a JSON path into a result, such as `$(tasks.scan.results.report.total)`. Use the task for an expression a reference can't take, such as a filter.

### Common problems

| Symptom | Cause | Fix |
| --- | --- | --- |
| The task succeeds, but `evaluation` is empty, and the log shows `TypeError [ERR_INVALID_ARG_TYPE]` | The expression matched nothing. | Check it against the JSON. Expressions start at `$` and are case-sensitive. |
| The task fails with `Invalid JSON string passed to task` | **Json** isn't valid JSON, such as an object with unquoted keys. | Check what the earlier task returned, under **View Details** on the run page. |
| The task fails with `Invalid mandatory parameters. Check log for details`, after `The parameter 'query' is not defined or empty` | The task needs both **Json** and **Query Expression**, although the form marks neither as required. | Fill in both fields. |

## MongoDB Query Execution

Executes a provided query against a mongo databases endpoint.

- **Slug:** `mongodb-query-execution`
- **Type:** `template`
- **Revision:** 1
- **Image:** `rtsp/mongosh`

**Parameters**

| Label | Name | Type | Required | Default | Helper text |
| --- | --- | --- | --- | --- | --- |
| MongoDB database host | `host` | Text | Yes |  | A valid, reachable mongo db endpoint |
| MongoDB database port | `port` | Number | Yes |  |  |
| Database name | `database` | Text | No |  | The database name used in the connection string |
| Database username | `username` | Text | No |  | The username to use for running the query |
| Database password | `password` | Secured | No |  |  |
| TLS enabled | `tlsenabled` | Boolean | No | `false` |  |
| Authentication mechanism | `authenticationMechanism` | Select | Yes | `DEFAULT` |  |
| Query | `query` | Text Editor - JavaScript/JSON | Yes |  |  |
| Response file path | `ouputfile` | Text | Yes |  | File path to store the query's output response |

No results.

## Run Python Script

Execute a Python script. The returned result of the script is returned as the result value of the task.

- **Slug:** `run-python-script`
- **Type:** `script`
- **Revision:** 2
- **Image:** `boomerangio/worker-python:0.0.3`

> [!WARNING]
> Revision 1 does nothing and ends `succeeded`: the command it calls is no longer in the task image. Later revisions work. Upgrade a node pinned to revision 1 in the editor. See [Some older task revisions do nothing](https://www.useboomerang.io/docs/flow/main/introduction/known-issues#some-older-task-revisions-do-nothing).

**Parameters**

| Label | Name | Type | Required | Default | Helper text |
| --- | --- | --- | --- | --- | --- |
| Python Version | `pythonVersion` | Select, read-only | Yes |  | Python 3 or Python 2 only. |
| Additional Python Packages | `pythonPackages` | Text Editor - Text | No |  | "Requirement specifier format": www.ibm.biz/BdfMmj |
| Python Arguments | `pythonArguments` | Text | No |  | Command line arguments. |
| Python Script | `pythonScript` | Text Editor | Yes |  | Python script to execute. |
| Output file path | `outputFilePath` | Text | No |  | File path where the script output will be written. |

**Results**

| Name | Description |
| --- | --- |
| `output` | Python script standard output standard and error content. |