Upgrading Assets Server

When upgrading an existing version of Assets Server (server and client) to a newer version of Assets Server, the server and client application is upgraded while your data, server configuration and log files are left in place.

The process of upgrading is as follows:

1. Creating a backup of the existing installation
2. Reviewing optional steps (before upgrading)
3. Stopping your current server
4. Installing Assets Server
5. Configuring Assets Server
6. Reviewing optional steps (after upgrading)
7. Starting Assets Server
8. Testing Assets Server

Before you start

Before you start the upgrading process, please do the following:

1. Read this article in full so that you are fully aware of the steps that need to be followed and the order in which they need to be performed.
2. Familiarize yourself with the changes that were made in the various releases by reading through the Release Notes for Assets Server and the Release Notes for Assets.

1. Creating a backup of the existing installation

Make sure you have a recent backup of your current environment.

Because all data is stored on the file system, all data in the following Assets Server folder locations should be backed up:

• Elvis Hot Data
• Elvis Shared Data
• Config

2. Reviewing optional steps (before upgrading)

Depending on the version of Assets Server that you are upgrading from or to, some additional steps may have to be manually performed before Assets Server is installed.

Review the information below and implement where applicable.

Upgrading to Assets Server 6.73 or higher

• Internal plug-ins. The use of internal plug-ins has been marked as deprecated. During the upgrade, the config/plugins/samples folder is cleared (except for some /internal samples). When the samples from the version that is upgraded from need to be maintained, create a backup of this folder first before upgrading.

3. Stopping your current server

Stop your current Assets Server from running.

4. Installing Assets Server

Download the installer from the software download page, run it and follow this instructions on screen. It will automatically detect the existing version and will replace all application files. Your data, configuration and log files will not be touched.

5. Configuring Assets Server

During the Server installation, a folder named clean-example-config-x.x.x is created in the main Config folder. It contains a clean copy of the latest configuration files.

Use it as a reference for any new configuration options that are available which you might want to make use of.

6. Reviewing optional steps (after upgrading)

Depending on the version of Assets Server that you are upgrading from or to, some additional steps may have to be manually performed after Assets Server has been installed.

Review the information below and implement where applicable.

Upgrading to Assets Server 6.57 or higher

• Integration with Studio Server or Enterprise Server. The metadata selector field group 'Enterprise' has been renamed to 'Studio'. When the 'Enterprise' group is used in the custom-assetinfo.xml file, manually change this to 'Studio'.

Upgrading to Assets Server 6.63 or higher

• Permissions. From Assets Server 6.63 onwards, Rules are now created separately for files, Collections, and folders. For details, see Controlling user access to folders and files in Assets Server.

One of the most noticeable changes is that Rename, Move, and Delete permissions do not apply to the selected folder, but only to the sub folders.

When upgrading from a previous release, existing Rules are automatically split into these separate rules. Each Rule covers part of the Rule that existed previously.

After the upgrade, the permissions closely mimic the previous permission setup, thereby easing the transition for users to the new permission system.

Verify the generated Rules, and tweak or remove them to match the user requirements.

Upgrading to Assets Server 6.64 or higher

• Multi-tiered storage. A fix has been put in place whereby the storage engine pattern is now case-insensitive, as originally designed.

In previous versions, this issue resulted in files ending up in the default file storage folder instead of in the configured folder.

Should any files exist in the default folder instead of in the configured folder, correct this by running the following tool in the Management Console:

Tools > Manual upgrades > Recover misplaced asset files

Upgrading to Assets Server 6.75 or higher

• REST API Search. Search results that contain many Collections can result in higher CPU load on the server than expected. This is caused by the four thumbnails that each Collection preview contains. To reduce the performance impact of collecting the thumbnail hits, the default value for the returnThumbnailHits parameter in the REST API - search has been set to false. When you are using an integration that relies on container thumbnail hits to be returned, add returnThumbnailHits=true to the search.

Upgrading to Assets Server 6.79 or higher

• Search Presets and Bookmarks. Assets Server 6.79 replaces Search Presets by Bookmarks. Unlike Search Presets, Bookmarks also save selected filters and applied filter values, metadata fields shown in various panels and thumbnail tiles, and selected view modes and zoom levels. If a Search Preset that is upgraded to a Bookmark requires any of these to be specifically set, then this needs to be done as an extra step after upgrading.

To do this, log in to Assets as a system administrator and open the Bookmark. Set the following areas as needed and then save the Bookmark:

• The Filter panel
• The Viewing mode (thumbnail view, list view, filmstrip view, or masonry view) and its zoom level

Note: When these modes are not specifically set for a Search Preset that is upgraded to a Bookmark, the settings from the user's own view are used.

Upgrading to Assets Server 6.82 or higher

• Analyzer for French. From Assets Server 6.82 onwards, the French analyzer now analyzes without accented characters, making it possible to find words such as Téléphone by searching for telephone and the other way around.

To make use of this, customers with either locale or analyzerLocale set to fr_FR require to reindex their Asset and Version indices.

Upgrading to Assets Server 6.83 or higher

• Metadata: Suggestions for the standard and custom multi-value fields now support tags with a mix of lower case and upper case (again). The release of Assets Server 6.73 contained a fix which involved the conversion of tags with text in a mix of lower case text and upper case text, to text in all lower case.

This unfortunately broke the autosuggestion functionality in the multi-value fields: suggestions now only appeared under certain conditions, or did not appear at all. This is especially problematic for the creatorName field because users typically type names by starting it with a capital letter. Other editable multi-value fields were affected as well:

• creatorName
• followers
• language
• productName
• subjectPerson
• tags
• tagsFromAI
• type

Support for mixed cases is now available for these standard multi-value fields and the custom multi-value fields by setting the data type of the field to 'completion'.

<field name="cf_myCompletionField" group="General">
	<storage storeInMetadata="true" />
	<compass index="tokenized" store="yes" excludeFromAll="false" />
	<data editable="true" datatype="completion" multivalue="true"/>
	<description>
          My custom field with tag completion suggestions.
	</description>
</field>

When upgrading from a system in which multi-value fields need to have this functionality restored, datatype="completion" needs to be added to the definition of the field in the custom-assetinfo.xml file, followed by a re-indexing of the system.

<fieldExt name="creatorName">
	<data datatype="completion"/>
</fieldExt>

Upgrading to Assets Server 6.95 or higher

• Thumbnails and previews for audio files. Thumbnails and previews for audio files display the wave form (spectral) of an audio file. Regenerating the thumbnails and previews (for all files) can be done by running the following tool in the Management Console:

• Tools > Asset processing tool. Enable the option 'Regenerate thumbnails and previews'.

Tip: Users can also regenerate thumbnails and previews for each file individually by right-clicking the file and choosing 'Regenerate thumbnail' from the context menu.

Upgrading to Assets Server 6.102 or higher

• The syntax to generate logging has changed. The Log4j library has been updated from version 1.x to version 2.20. As a result the syntax to generate logging has changed. To update the log settings, perform the steps below.

External configuration files with a .txt extension can continue to be used as long as they contain .properties content and have a name that includes .properties, as it was in earlier versions of Assets Server.

Example: logging.properties.txt.

Configuration from the external files will still override the default settings. However, slight changes to the syntax have been made:

When setting the logger level for a specific class, a property first needs to be assigned to the logger with any name you choose.

Example: logger.nameGivenByMe.

Then, assign the name attribute for that property with the path to the class.

Finally, assign the level property.

log4j.logger.com.ds.acm.warnings.level = INFO

logger.warningsLevel.name = com.ds.acm.warnings
logger.warningsLevel.level = INFO

When configuring an appender, start by specifying a name for that appender (such as appender.myName), and then assign the type property for that appender. Use 'Console' to log to the console, 'SMTP' to send log e-mails, or other custom appenders created as plug-ins.

appender.MyName.type = MyCustomAppender

Afterwards, set the name property for that appender, and reference it in the appender reference of the rootLogger.

appender.console.type = Console
appender.console.name = MyName
rootLogger.appenderRef.console.ref = MyName

It is also possible to configure filters or layouts for an appender :

appender.consoleAppender.filter.threshold.type = ThresholdFilter
appender.consoleAppender.layout.type = PatternLayout

appender.consoleAppender.layout.pattern = .....

Upgrading to Assets Server 6.120 or higher

• Changes to managing internal users and user groups. When no external LDAP system is available, managing users and user groups is done in Assets Server itself. This is typically the case when a very small setup is used such as a demo environment installed on a single laptop.

In previous versions of Assets Server, such users and user groups were managed in the internal-users.properties.txt file.

To make this process safer and more efficient to manage, internal users and user groups are now managed in the Management Console.

When upgrading from Assets Server 6.119 or lower to Assets Server 6.120 of higher, users that are defined in the internal-users.properties.txt are automatically migrated to the Elasticsearch index.

After migration, the index is the single source of truth and the properties file is no longer used.

7. Starting Assets Server

At this point, Assets Server is ready to be started.

Important: As part of the upgrade process, Assets Server will automatically update the index. Depending on the size of the index, this can either take a few moments or it can take some time. Do not restart Assets Server until this process is finished. Use the Paramedic page of Assets Server (access Assets Server > Support Tools > Elasticsearch > Paramedic or use URL localhost:9200/_plugin/paramedic/) to monitor the progress.

8. Testing Assets Server

Verify that Assets Server is working properly by using Assets. Perform tasks such as uploading some files, searching for them, downloading or sharing them, or any other tasks that are part of your daily workflow.