# Create Symbolic Links

This function is used to create symbolic links. The created links can be absolute or relative and can be to a file or folder. Absolute links will always refer to the same item even if it is moved to a different location. Relative links remain valid if the containing folder and the item being referenced are both moved.

Choose if you want the symbolic links placed in a specified path or to a path relative to the folder containing the original file. Relative paths are specified by the number of levels up from the file's containing folder. Zero levels implies that the new folder structure should be in the files's containing folder. One level implies that the new folder structure should be in the parent of the file's containing folder, etc.

A specified path may contain any of the escape sequences described in Escape Sequences. At runtime the path must resolve to be:

- An absolute path starting with /
- A path relative to the user home folder starting with ~/
- A path beneath the track's containing folder, starting with ./

Choose up to three fields to be used as folders to be appended to the absolute or relative base path. When the path is constructed if you specified Album Artist and the field is empty, Artist will be used. If the value associated with a chosen field is empty an error will be issued unless a placeholder is specified. Note that if a non empty placeholder is specified and a field is not specified, the placeholder will be used. This allows the specification of a fixed value for a path component.

Transformations can be applied to each of the three fields to be optionally appended. To configure the transformations press the Transformations... button. A panel will be displayed containing the transformation settings.. Close the panel by clicking off the panel or by pressing the Escape key. For more information see Statement Transformations.

You can also elect to specify a rename template. If a template is not specified, the original file (or folder) name will be appended to the destination path. If a template is specified it will be applied. If the template contained a Folder Start construct, the constructed folder will be appended to the path. The constructed filename with the original filename extension (unless creating folder links) will then be appended to the path. The rename template can be chosen from the popup list or manually entered. The only reason to manually enter the template name is if you wish to specify the name at runtime. The template field may contain any of the escape sequences described in Escape Sequences.

To summarize the destination location is calculated as follows:

- an absolute or relative base path.
- optionally up to three path components based on field contents.
- an optional path component constructed by the Folder Start construct in a rename template.
- The original filename or a constructed filename from a rename template, followed by the original filename extension.

By default, the function will always be performed. You can specify to only perform the function if it is part of a compilation or not part of a compilation. This facilitates having two different back to back Move steps. One which handles the non compilation state and one which handles the compilation state.

You can specify what to do if a file already exists at the destination. You can choose to perform the default operation or to skip the symlink creation or always replace the existing file. The default operation while not Batch Processing is to be presented with a dialog where you can choose what to do. The default operation while Batch Processing is to log an error message. Note that while Batch Processing, default and skip are identical.

The function sets the Retained Path 1 property to the destination on success. On failure, the property is emptied.

The function will set the Retained Path 2 property to the contents of the link on success. On failure, the property is emptied.

You can preview the function's application based on the files currently selected in the main window. The results are displayed in the Log Viewer.