Preparing for the upgrade

Should I upgrade the existing codebase or make a clean install using the latest version?

Consider the changes in API between the different versions

• Litium 4 and 5 the products API was changed.
• Litium 5 and 6 the customers and media API were changed.
• Litium 6 and 7 the websites API was changed.

There are three upgrade paths. You must choose which one to follow.

1. Make a clean install of Litium and discard both the current solution and the current database.
   • If you need to migrate data from the old database, you must use database migration scripts.
   • Existing layout and functionality in the old solution that you want to keep, need to be migrated and adapted into the new templates.
      
2. Make a clean install of Litium but keep the current database.
   • Only code in use will be moved to the new solution, making this a good opportunity to clean an existing solution of all unused code.
   • Existing layout and functionality in the old solution that you want to keep, need to be migrated and adapted into the new templates.
      
3. Upgrade the solution and use the current database.
   • All custom functionality that references parts of the Litium API that is no longer available, need to be re-written.

WebForms and Web controls

If you are still using WebForms, consider upgrading to Microsoft MVC to get benefits for all performance improvemenets and be more future proof. All Litium web controls for websites (CMS) need to be upgraded in the project and web controls for other areas (products, customer, ecommerce) may need changes as well to adapt the new websites API.

Does the site use any add-ons, payment providers or other compiled components that depend on Litium?

Verify that there is an upgraded version of the add-on that supports the new Litium version. The supported versions information is displayed on the add-on download page. If an add-on is not supported yet, contact Litium support to get information about add-on compatibility and upgrade options.

Is the solution integrated with other systems?

Consider the following when upgrading a solution that has integrations:

• All integrations that populate data into the Litium database should be stopped before making database backups.
• When deploying new versions of the integration code to the Windows Service or the website, you need to ensure that the job can restart from the beginning, or continue from the last point, in order not to lose any work when the Windows Service or website restarts.
• If the integration job cannot handle restarts, all jobs need to finish before new code can be deployed. In general, it is recommended to wait until any current integration job has finished before interrupting the service or website.
• Since the integrations are not running during the service window, any changes to the data in the source system (usually an ERP or PIM system) during the service window must be re-populated to Litium before the site is brought back online.

Does the website use the Excel import/export add-on?

This add-on was used for Litium versions earlier than 5 to import product information. Since Litium 5 this feature is built-in, so all import and export files need to be adjusted to be compatible with the Litium 5 import/export format.

Does the website use the pricelist import/export feature?

Since Litium 5 pricelists are imported/exported through the built-in import/export feature, so all import and export files need to be adjusted to be compatible with the Litium 5 import/export format.

Is the same product published in several product groups?

In Litium 4.8 it was possible to have relations between products in some assortments. This is no longer possible. A workaround is to rename the relations to “AssortmentName” and “RelationTypeName”.

Should I consolidate sites in different languages into one field framework?

The fields in the field framework now support several languages. This means you can use the same fields for multi-language sites, instead of having to create language-specific fields for each language version.

How should the upgraded website be released?

There are two options to deploy an upgrade:

• Start the upgraded site next to the old one and then redirect the domain when it is time to go live. All data added in the old site needs to be migrated to the new site, once the traffic is directed there.
• Stop the site during the upgrade and display a maintenance page. This is a suitable solution for smaller sites.

Does the solution contain area panels?

These panels are loaded in a frame for re-factored areas (Websites, Products, Customers and Media). They will still work after the platform upgrade first after the panel itself is updated in the upgrade project.

Does the solution contain entity panels?

Panels implemented through templates are no longer supported in the re-factored areas (Websites, Products, Customers and Media). These need to be implemented as field types. More information on creating custom field types can be found in this article.

Is search against Media or Customers used?

These areas no longer use Lucene for search, so other solutions need to be implemented, for example by using a data service.

How should file metadata be handled?

If you are upgrading from a version earlier than 6, metadata for files in the Media area must be set up as new fields in the field framework.

Back office UI for organizations and organization hierarchy

In Customers back office, the search function should be used to view organizations instead of the tree view to the left. The child organizations in Litium 7 are defined as organization pointers. In Litium 7 an organization can point to multiple other organizations, so any organizational structure can be represented.

Are there any newsletters set up in the project?

The Newsletter area has been removed from Litium. E-mail marketing can now be handled through the Apsis Connector add-on.

Active Directory usage

The direct Active Directory connection for logins was removed in Litium 6. Use Active Directory Federation Service (ADFS) for login instead.

Instructions on setting this up as an external login provider can be found here.

Changing the .NET target framework version

When upgrading between different versions of Litium you might need to change the target framework version (e.g. 4.8 to 7 etc.). If you have many projects, changing the target framework version could take a lot of time, but with this PowerShell script the task only takes a few seconds for all projects.

Start the Package Manager Console, that is a PowerShell console inside Visual Studio, from Tools > NuGet Package Manager.

Run the following PowerShell script in the Package Manager Console. The script below has the target framework version set to 4.7.2. If you need to change to another version you can change the version number in the script.

function update-solution {param ($item = $dte.Solution.Projects)$item | % {if ($_.Type -eq $null){$p = $_.Object} else {$p = $_}if ($p.Type -eq 'Unknown') {if ($p.ProjectItems -ne $null) {update-solution $p.ProjectItems}}elseif ($p.Type -ne $null) {$prop = $p.Properties.Item('TargetFrameworkMoniker');if ($prop.Value -ne ".NETFramework,Version=v4.7.2") {$name = $p.ProjectName;Write-Host "Change .Net framework to 4.7.2 for project $name" -ForegroundColor DarkYellow;try {$prop.Value = ".NETFramework,Version=v4.7.2"} catch {Set-ItemProperty ((get-project $name).FullName) -name IsReadOnly -value $false;$prop.Value = ".NETFramework,Version=v4.7.2"}}}}} & update-solution