Rename Library File

Controlled node

Overview

The Rename Library File node allows you to programmatically rename files stored in your project's library. This is useful for organizing files, updating naming conventions, or dynamically renaming files based on workflow logic.

When triggered, the node takes a file reference and a new name, then updates the file's metadata in the library. The node outputs the updated file object with the new name upon success, or an error object if the operation fails.

Inputs

Input	Type	Description	Default
Run	Event	Triggers the rename operation.	-
File	FileSource	The file to rename. Accepts a single file object or an array (first item is used). Must contain a valid file id.	-
Name	Text	The new name for the file. Must be a non-empty string. The file extension should be included if you want to preserve it.	-

Outputs

Output	Type	Description
Done	Event	Fires when the rename operation completes, regardless of success or failure.
File	Data	On success: the updated file object containing the new name and metadata. On failure: an object with an error property containing the error message.

Runtime Behavior

When the Run event fires, the node performs the following actions:

1. Validation: Checks that both file and name inputs are provided and valid. The name must be a non-empty string.
2. Project Context: Retrieves the current projectId from the workflow runtime context.
3. File Resolution: If the file input is an array, it selects the first element. Validates that the file object contains an id property.
4. Rename Operation: Calls the library system to rename the file using librarySystem.renameFile(projectId, file.id, newName).
5. Output:
   • On success: Outputs the renamed file object to the file output and fires done.
   • On failure: Outputs an error object {error: 'Error renaming file: <message>'} to the file output and fires done.

File Extension Handling

When providing the new name, ensure you include the file extension (e.g., .pdf, .txt) if you want to preserve the file type. The node does not automatically append extensions.

Error Handling

If the file cannot be renamed (e.g., permissions issues, file not found, or invalid name), the node will output an error object to the file socket rather than throwing a workflow error. Always check the output structure when handling errors.

Example

Here's an example of how to use the Rename Library File node in a workflow:

1. Get Library Files node outputs a list of files from a folder.
2. For Each node iterates over the files.
3. Text node constructs a new name using template variables (e.g., "Report_{{date}}_{{element.name}}"), where element is the current file from the For Each loop.
4. Rename Library File node receives:
   • file: The current file object from the loop
   • name: The constructed new name from the Text node
   • run: Triggered by the For Each loop event
5. Assert node checks the file output to verify the rename was successful (checking that the output doesn't contain an error property).

[Get Library Files] 
       ↓ (files list)
[For Each] → [Text: "Report_{{date}}_{{element.name}}"]
       ↓ (element)              ↓ (newName)
[Rename Library File] ←───────┘
       ↓ (file output)
[Assert: check no error]
       ↓
[Done]