You can rename a file stored in a File with Versioning field by using the File Renaming script. The script works by updating a file's name with the text entered in a separate Short Text field. To run the script, reference it with a Script action and then trigger the action with an action button or a rule. This allows you to easily rename files without having to download, edit, and re-upload them.

If you are running Release 22 or later, the File Renaming script is included on  Agiloft's servers or in the script folder on your server for on-premise installations. If you are running a release earlier than Release 22, whether your system is on-premise or hosted by  Agiloft, contact our Support Team for assistance with running the File Renaming script.

The script has the following features and limitations:

• If the file in the File with Versioning field has multiple versions, the script only renames the most recent version of the file but retains the previous versions.
• If the File with Versioning field contains multiple files, the script renames the first file and removes the other files. For this reason, we recommend using the script only when a File with Versioning field contains a single file.

• If the Short Text field contains invalid characters in the file name (such as "?"), the script replaces those characters with an underscore ("_").

• If the Short Text field contains a file extension that matches the extension of the existing file, the file extension is ignored. If the file extension doesn't match, it's added to the file name. The script cannot change the file type. For example:

  Existing File Name	Text in Short Text Field	Updated File Name
  ABC.docx	PQR.docx	PQR.docx
  ABC.docx	PQR	PQR.docx
  ABC.docx	PQR.xlsx	PQR.xlsx.docx

Configure Your System

The following steps provide one way of configuring a KB to work with the File Renaming script. Depending on your own KB's configuration, the exact fields, actions, or rules you create might differ from the ones described here. For instance, in this article we use the Attached File field in the Attachments table of the Standard System Demo, but the script can work in any table and with any File with Versioning field.

Create the Fields for Renaming Files

Start by creating two fields in the Attachments table, a Short Text field and an action button.

Create a Short Text Field

Start with the Short Text field, which will hold the new file name.

1. On the nav bar, go to Attachments > Setup Attachments to open the Attachments table wizard.
2. Click the Fields tab and go to New > Short Text.
3. Label the field "New File Name."
4. Click the Display tab and set the width of the input field to 30 characters. In your own system, you might enter a different value based on your record's layout.
5. Click Finish.

Create an Action Button

Next, create the action button, which the user clicks when they want to run the script and rename the file.

1. While still on the Fields tab of the Attachments table wizard, go to New > Action Button.
2. Label the field "Button: Rename File."
3. Choose to display the field as a Button with Text that says "Rename File."
4. For after the action is executed, choose Save Record. Later, we'll add the action that the button runs.
   Selecting Save record
5. Click the Display tab, and select "Neither the label nor the instruction" for both when viewing and editing the field.
6. Click Finish.

Create the Actions for Running the Script

The script needs a few actions, all of which are contained in an If-Then-Else action that the action button runs.

Create a Script Action

Start with a Script action, which runs the File Renaming script.

1. While in the Attachments table wizard, click the Actions tab.
2. Click Create Script Action.
3. For the Action Name, enter ATTACHED_FILE_NAME_UPDATOR_V2.jar. You must enter the name exactly as indicated for the script to work.
   Action name showing .jar title
4. Add a description and click Finish.

Create a Validate Action

Next, create a Validate action to prevent the script from running if the Short Text field doesn't have a value.

1. While still on the Actions tab of the Attachments table wizard, click Create Validate Action.
2. For the Action Name, enter "Must Enter a New File Name" or similar.
3. Complete the Description and Error Message fields. For the Error Message, remind the user that they must enter a value in the New File Name field to rename the file.
4. Make sure "Prevent saving record if the search condition is met" is selected and click Finish.
   Prevent saving record if the search is not met

Create an Update Fields Action

Create an Update Fields action to clear the Short Text field after the script runs. This makes sure users can enter another file name when desired.

1. While still on the Actions tab of the Attachments table wizard, click Create Update Fields Action.
2. For the Action Name, enter "Blank Out New File Name" and provide a description.
3. Click the Fields tab and select the New File Name field.
4. Click the Values tab, but don't enter anything in the field. Leaving the field empty clears it of any value when the action runs.
5. Make sure "Standard text" and "Overwrite the existing value" are both selected.
   Selecting Standard text and Overwrite
6. Click Finish.

Create an If-Then-Else Action

Lastly, create the If-Then-Else action to contain each of the previous actions we created.

1. While still on the Actions tab of the Attachments table wizard, click Create If-Then-Else Action.
2. For the Action Name, enter "Rename File" and provide a description.
3. Click the Details tab and then click Add If.
   1. Click Simple to create a Simple filter.
   2. Select the New File Name field.
   3. Select the "equals, =" operator.
   4. Select Variable and enter $NULL.
      
   5. Click Finish.
4. Click Add Action.
   1. Select the V: Must Enter New File action.
   2. Click Finish.
5. Click Add Else.
6. Click Add Action.
   1. Select the S: ATTACHED_FILE_NAME_UPDATOR_V2.jar action.
   2. Click Finish.
7. Click Add Action again.
   1. Select the U: Blank New File Name action.
   2. Click Finish.
8. Click Finish. When complete, your If-Then-Else action should look like this:
   

Create the Short Text Constant

Next, create a Short Text constant that the script will use to update the file name.

1. Click the Setup gear in the top-right corner and go to System > Manage Global Variables.
2. Go to New > Short Text Constant.
3. For the Name and Label, enter attachment__fileNameUpdator. Make sure to use two underscores ("__") or the script won't work.

4. For the Global Variable Value, enter attached_file:new_file_name.

   The name to the left of colon is the field containing the file that you want renamed. The name to the right is the field where users enter the new file name. If you're using different fields in your own system, enter them here.

5. Click Finish.

Configure the Layout and Test the Script

Lastly, update the action button, add the fields to the layout, and test that the script works.

Add the Action to the Action Button

Update the action button to run the If-Then-Else action that you created earlier.

1. On the nav bar, go to Attachments > Setup Attachments to open the Attachments table wizard.
2. Click the Fields tab and edit the Button: Rename File field you created earlier.
3. On the General tab, select Execute Actions and click Add Action.
4. Select the I: Rename File action and click Finish. The action is added to the action button.
   Add Action
5. Click Finish.

Add the Fields to the Layout

Next, add the fields you created to the layout in the Attachments table.

1. While still in the Attachments table wizard, click the Layout tab.
2. Add the New File Name field and Button: Rename File action button somewhere on the layout.
3. Click Finish.

Test the Script

Finally, test that the script works as intended.

1. Click the Attachments table on the nav bar.
2. Edit a record with a file in the Attached File field.
3. Enter a new file name in the New File Name field.
4. Click Rename File. If you configured everything correctly, the record is saved and file is renamed with the text you entered.