With the 5.10 release, a new transcode system is introduced.

The new transcode system has been written from scratch and is much easier to configure than the old transcode system. The main capabilities of the new transcode system are described here.

When upgrading existing environments to 5.10, the old transcode system is still used. However, it is highly advised to migrate to the new transcode system while being on 5.10, since the old transcode system is deprecated and can not be used in future versions.

This page describes the main things to be aware of in relation to the migration to the new transcode system.

Migration

In 5.10.0-5.10.7, the old transcode system was automatically migrated to the new transcode system when upgrading.

From 5.10.8, the migration from the old transcode system to the new transcode system must be performed manually.

Environments that have been on 5.10.0-5.10.7

The automatic migration that was run on 5.10.0-5.10.7 versions (both inclusive) did not migrate profiles. Instead, profile-like setups had to be configured with the Generate asset renditions automation step.

If you upgrade a site to 5.10.8 (or newer) and start using the “No-security channel folders” parameter on formats to control publicly available renditions, please be aware that existing publicly available renditions will always remain publicly available, unless the automation step Generate asset renditions is still used to make the renditions private again.

We recommend using the “No-security channel folders” parameter on formats to control which renditions that are publicly available. If you decide to do this and you have previously used the automation approach, please run the following script to ensure that renditions can be made private again based on the “No-security channel folders” parameter of the configured formats: scripts/enforce_channel_based_ignore_security.sql at main · Digizuite/scripts. NB: When you run this script, it will be very difficult to revert back to an automation-based approach for controlling publicly available renditions.

Migration details

To manually migrate from the old transcode system to the new transcode system, please see the section Manual Migration Guide.

The script migrates as many old media formats as possible to new formats. In particular, a new format with the same name as the old format is created, and then the old format is mapped to the new format. This is only done for old media formats that can be mapped to a supported format type in the new transcode system. Please contact R&D if you have a use case for a format type that is not supported in the new transcode system.

An overview of all formats can be seen on the system administration page in the Media Manager. If a format is mapped to an old media format, this can be seen in the “Mapped media formats” parameter when viewing the details of a format.

Open

When an old media format is mapped to a new format, please be aware of the following:

• All changes to the old media format are ignored.

• Existing renditions are not re-generated. Thus, the existing renditions will be used when requesting renditions of existing assets in the new format. This is also the case if generating the rendition with the new format definition would lead to a different rendition than the existing rendition. As described in DC 5.10 Breaking changes - Transcode system | New thumbnail formats, it is possible to use the “Generate asset renditions” automation step to force existing renditions to be re-generated.

• For new assets, the new transcode system and the new format are used to generate renditions. This is also the case if a rendition of the old media format is requested.

• Renditions of the format can still be requested with the ID of the old media format. This is mainly relevant for backward compatibility reasons.

• If a format was made available both through “Profiles and destinations” and “Asset type configuration”, then “Asset type configuration” will take precedence over “Profiles and destinations”.

Manual migration guide

A customer can be migrated from the old transcode system to the new transcode system by following these steps:

• Ensure that the environment you are working on is on version 5.10.8 or a later patch release of 5.10.

• Ensure that there are no diffs in Configuration Management.

• Run the migration script scripts/transcode_system_migration.sql at main · Digizuite/scripts.

  • The script will emit some warnings on formats that could not be migrated. These can be ignored. However, please ensure that you read “Things to be aware of” after having followed this guide.

• Clear the LegacyService cache.

• Calculate a diff in Configuration Management and export the following actions:

  • Update column:

    • All format actions.

    • All member_group actions.

  • Delete column:

    • All format actions.

Things to be aware of

• Publicly available renditions: The migration scripts relies on profiles to migrate no-security renditions. This means that renditions must be publicly available through an active profile setup to remain publicly available after the migration. In particular, be aware of the following:

  • Deleted profiles: If a profile has been deleted but renditions created via this profile are still publicly available, the renditions will stop being publicly available.

  • Asset type configurations: If a rendition is only made publicly available by storing it on a LaxSecurity destination via an asset type configuration, the rendition will stop being publicly available.

• Unsupported media format type: The new transcode system supports a limited set of format types. All old media formats that do not have a corresponding format type in the new transcode system can not be automatically migrated to a new format. If a media format is used and has not been migrated, consider if one of the supported format types in the new transcode system can be used instead. Otherwise, reach out to R&D to share your use case.

  • All non-migrated media formats can be identified by running the following SQL query against the database after upgrading: .

• Special ImageMagick commands: If an old media format is defined with an ImageMagick command that refers to a local file on the server, renditions of the corresponding migrated format can not be generated with the new transcode system. This can e.g. be the case if a custom profile or a special watermark is used. An example of such an ImageMagick command is: %infile%[0] -profile "D:\my\local\file\path\custom_profile.icc" %outfile%. If a local file is referenced, the corresponding migrated format must be edited manually.

  1. The media formats for which this potentially is an issue can be identified by running the following SQL query against the database after upgrading: .

• Video thumbnails: If the OOBE configuration layer is not used, please be aware that selecting a custom video thumbnail in MM will not work without setting up an automation that force generates thumbnails when the FrameAccurateThumbnail metafield changes. An example of an automation that does this can be found here: configurations/OOBE/5.10.0/automations/oobe_republish_on_frameaccurate_thumbnail_changed.dcl at master · Digizuite/configurations.

PROD environment migration guide

In some cases, new formats might be created and mapped to old media formats without running the migration script in the previous section.

This might e.g. be the case when upgrading a PROD environment, where configuration management is used to create and map formats.

In this case, the renditions need to be migrated from the database table asset_filetable, used by the old transcode system, to the database table Renditions, used by the new transcode system. If this is not done, existing renditions will not be re-used. Renditions will therefore be generated when they are requested the first time.

To migrate the renditions based on existing formats and their mapped media formats, please run the following script: scripts/migrate_renditions.sql at main · Digizuite/scripts.

LaxSecurity destinations

In the old transcode system, it was possible to generate renditions and make them available at specific destinations via asset type configurations or profiles. If a destination was configured with LaxSecurity set to true, the renditions stored in this destination would be publicly available.

In the new transcode system, it is not possible to generate renditions at specific destinations. Instead 2 alternatives are available:

1. Use the “No-Security channel folders” settings on formats. In this case the format is considered publically available the moment the asset is added to one of the specified folders. Do note that this does not cause the rendition to be generated. If the rendition is not generated when it is requested, the standard logic of waiting for the transcoding to be completed still applies. To get around this, specify the channel folder in “Pre-generate channel folders” also.

2. The automation step “Generate asset renditions” can be used to generate renditions with IgnoreSecurity set to true. This makes the generated renditions publicly available.

We recommend using option 1.

Revisit formats

Although not strictly necessary, the introduction of the new transcode system provides a good basis for revisiting the formats that are defined for existing customers. Maybe some of the old media formats are no longer needed. Maybe some of the automatically mapped formats can be mapped better manually, for instance, utilizing the support for webp and transparency.

DFO or other search-based integrations

If a customer is using a DFO integration using GetEpiserverAsset, you will need to build a new search index. You can do this by changing an output parameter to have tooltip enabled, saving and rebuilding.

This is also required for other search2 searches that are used by integrations, that are returning assetstream urls.

Renditions are stored in a new table after migrating to the new transcode system, which search2 will not know about unless it is rebuild. Therefore if it is not rebuild, the search will not return the new formats.