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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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.