<!-- BusyBot node reference — https://busybot.net/tools/move-binary-data/ -->

> Node: Move Binary Data (`move_binary_data`) · Action (binary) · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# Move Binary Data

> Convert data between binary and JSON properties

## Overview

The Move Binary Data tool provides two conversion modes: (1) binaryToJson — reads binary data from an item, decodes it using a configurable character encoding, and places the result into the item's JSON properties (as a parsed object, raw string, or base64 string); (2) jsonToBinary — reads JSON data from an item, serializes it (via JSON.stringify or raw string), encodes it with iconv-lite, and attaches it to the item as binary data. Supports dot-notation deep key access for both source and destination properties. Uses iconv-lite for encoding/decoding with BOM support. No external API calls.

**Category:** Core Nodes  
**Tool Name:** `move_binary_data`  
**Version:** 1

**Appearance:** Icon: `lucide-ArrowLeftRight` | Color: `#7722CC`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool does not require any credentials.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Mode | `options` | No | `binaryToJson` | Direction of data conversion. |
| | | | | Options: `binaryToJson` (move data from Binary to JSON), `jsonToBinary` (move data from JSON to Binary) |
| Set All Data | `boolean` | No | `true` | Whether all JSON data should be replaced with the data retrieved from the binary key. If false, data will be written to a single key. _(shown when Mode is `binaryToJson`)_ |
| Source Key (`sourceKey`) | `string` | Yes | `data` | The name of the binary key to get data from. Supports dot-notation for deep keys (e.g., "level1.level2.currentKey"). _(shown when Mode is `binaryToJson`)_ |
| Destination Key (`destinationKey`) | `string` | Yes | `data` | The name of the JSON key to copy data to. Supports dot-notation for deep keys (e.g., "level1.level2.newKey"). _(shown when Mode is `binaryToJson` and Set All Data is `false`)_ |
| Convert All Data | `boolean` | No | `true` | Whether all JSON data should be converted to binary. If false, only the data at the source key will be converted. _(shown when Mode is `jsonToBinary`)_ |
| Source Key (`sourceKey`) | `string` | Yes | `data` | The name of the JSON key to get data from. Supports dot-notation for deep keys. _(shown when Mode is `jsonToBinary` and Convert All Data is `false`)_ |
| Destination Key (`destinationKey`) | `string` | Yes | `data` | The name of the binary key to copy data to. Supports dot-notation for deep keys. _(shown when Mode is `jsonToBinary`)_ |
| Options | `collection` | No | `{}` | Extra conversion settings; which ones apply depends on Mode. |
| — Add Byte Order Mark (BOM) | `boolean` | No | `false` | Whether to add a special marker at the start of the file. Helps some programs understand how to read the file correctly. Only applies to BOM-aware encodings. _(shown when Mode is `jsonToBinary`)_ |
| — Data Is Base64 | `boolean` | No | `false` | Whether the source value is already a base64-encoded string that should be decoded directly to binary. _(shown when Mode is `jsonToBinary` and Convert All Data is `false`; hidden when Use Raw Data is `true`)_ |
| — Encoding | `options` | No | `utf8` | Character encoding to use for encoding/decoding the data. _(shown when Mode is `binaryToJson` or `jsonToBinary`)_ |
| | | | | Options: `utf8`, `ascii`, `utf16le`, `latin1`, `base64`, `hex`, `binary`, and every other encoding the platform supports |
| — Strip BOM | `boolean` | No | `true` | Whether to strip the Byte Order Mark from decoded text. Only applies to BOM-aware encodings. _(shown when Mode is `binaryToJson`)_ |
| — File Name | `string` | No | — | The file name to set on the binary data. _(shown when Mode is `jsonToBinary`)_ |
| — JSON Parse | `boolean` | No | `false` | Whether to parse the decoded string as JSON to produce a structured object. _(shown when Mode is `binaryToJson` and Set All Data is `false`; hidden when Keep As Base64 is `true`)_ |
| — Keep Source | `boolean` | No | `false` | Whether the source key should be kept after conversion. By default it will be deleted. |
| — Keep As Base64 | `boolean` | No | `false` | Whether to keep the binary data as a base64-encoded string instead of decoding it. _(shown when Mode is `binaryToJson` and Set All Data is `false`; hidden when JSON Parse is `true`)_ |
| — MIME Type | `string` | No | `application/json` | The MIME type to set on the binary data. Defaults to application/json. _(shown when Mode is `jsonToBinary`)_ |
| — Use Raw Data | `boolean` | No | `false` | Whether to use the string value as-is without JSON.stringify. Only applies when the value is a string. _(shown when Mode is `jsonToBinary`; hidden when Data Is Base64 is `true`)_ |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item — **except** when the source is missing. If the binary property named by Source Key is absent (`binaryToJson`), or the JSON value at Source Key is undefined (`jsonToBinary`), the item is dropped: it produces no output item and no error.

**Binary to JSON**

- With **Set All Data** on, the decoded text is parsed as JSON and becomes the entire item JSON — every original field is replaced. The file therefore has to contain valid JSON, or the item fails.
- With **Set All Data** off, the item JSON is kept and the decoded value is written at Destination Key (dot-notation creates the nested objects it needs). The value is a string by default, a base64 string with Keep As Base64 on, or a parsed object with JSON Parse on.
- The source binary property is removed unless Keep Source is on. When that leaves no binary properties at all, the output item carries no binary data.

**JSON to Binary**

- The serialized value is stored as binary at Destination Key. Objects are JSON-stringified; a string value is written as-is when Use Raw Data is on, and decoded from base64 when Data Is Base64 is on. Binary properties the item already carried are preserved.
- The stored binary carries `fileName`, `mimeType` and `fileSize`. MIME type defaults to `application/json`. When File Name is empty, a name is generated from the MIME type — for example `file.json`, `file.csv`, `file.bin`.
- Unless Keep Source is on, the source JSON is cleared: the whole item JSON becomes `{}` with Convert All Data on, or just the Source Key field is deleted with it off.

## Usage Examples

- Decode a binary PDF into a base64 string in JSON
- Convert JSON object to a binary JSON file
- Extract binary file content as UTF-8 text into a JSON property
- Convert a base64-encoded string from JSON into binary data
- Move binary CSV data into a JSON property for processing

## Example Configuration

Replace the item JSON with the decoded contents of a binary file:

```json
{
  "type": "move_binary_data",
  "parameters": {
    "mode": "binaryToJson",
    "sourceKey": "fileData",
    "setAllData": true,
    "maxConcurrency": 5,
    "options": {
      "encoding": "utf8",
      "stripBOM": true,
      "keepSource": false
    }
  }
}
```

Decode one binary property into a single JSON field:

```json
{
  "type": "move_binary_data",
  "parameters": {
    "mode": "binaryToJson",
    "sourceKey": "attachments.document",
    "destinationKey": "parsedContent",
    "setAllData": false,
    "options": {
      "encoding": "utf8",
      "jsonParse": false,
      "keepSource": true
    }
  }
}
```

Turn the whole item into a downloadable JSON file:

```json
{
  "type": "move_binary_data",
  "parameters": {
    "mode": "jsonToBinary",
    "destinationKey": "outputFile",
    "convertAllData": true,
    "options": {
      "fileName": "export.json",
      "mimeType": "application/json",
      "encoding": "utf8",
      "addBOM": false
    }
  }
}
```

Convert one nested JSON field into a binary file:

```json
{
  "type": "move_binary_data",
  "parameters": {
    "mode": "jsonToBinary",
    "sourceKey": "report.data",
    "destinationKey": "binaryReport",
    "convertAllData": false,
    "options": {
      "fileName": "report.bin",
      "mimeType": "application/octet-stream",
      "useRawData": true,
      "keepSource": true
    }
  }
}
```

Decode an uploaded file and parse it into a structured object:

```json
{
  "type": "move_binary_data",
  "parameters": {
    "mode": "binaryToJson",
    "sourceKey": "data",
    "destinationKey": "processedData",
    "setAllData": false,
    "options": {
      "encoding": "utf8",
      "jsonParse": true,
      "stripBOM": true
    }
  }
}
```

Export processed results as a file for a downstream upload node:

```json
{
  "type": "move_binary_data",
  "parameters": {
    "mode": "jsonToBinary",
    "sourceKey": "results",
    "destinationKey": "exportFile",
    "convertAllData": false,
    "options": {
      "fileName": "results.json",
      "mimeType": "application/json",
      "encoding": "utf8",
      "addBOM": false
    }
  }
}
```

Keep binary content as a base64 string in JSON:

```json
{
  "type": "move_binary_data",
  "parameters": {
    "mode": "binaryToJson",
    "sourceKey": "base64Data",
    "destinationKey": "decodedContent",
    "setAllData": false,
    "options": {
      "encoding": "utf8",
      "keepAsBase64": true,
      "keepSource": false
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Convert data between binary (file) and JSON properties — decode binary files into JSON or serialize JSON into binary files.

### Behavior notes

- **A missing source is a silent skip, not an error.** An item with no binary property at Source Key (or no JSON value there) is dropped from the run entirely. If you expect every item to convert, check the property name first — nothing appears on the Error output to tell you it did not.
- **Set All Data requires valid JSON.** In `binaryToJson` mode with Set All Data on, the decoded text is parsed as JSON and becomes the whole item. To pull in a plain-text or CSV file, turn Set All Data off and read the string from Destination Key instead.
- **The source is deleted by default.** Keep Source is off, so the binary property (or JSON field) you converted disappears from the output item. Turn it on when a later node still needs the original.
- **Convert All Data empties the item JSON.** In `jsonToBinary` mode with Convert All Data on and Keep Source off, the output item has no JSON left at all — only the new binary. Carry anything you still need on another branch.
- **This node moves data, it does not convert formats.** JSON becomes a JSON file, text becomes a text file. To parse a spreadsheet or a PDF, use the tool built for that format.