Instructions for Upgrading to Crafter CMS 3.1.0 from a previous 3.0.x version

Upgrade your Crafter CMS install, by following the upgrade guide Upgrading Crafter CMS.

Please note the following when upgrading to Crafter CMS 3.1 from 3.0:

  1. Groups are now at the system level instead of per site. By default, Crafter CMS has the following groups available after a fresh install: system_admin, site_admin, site_author, site_developer, site_publisher, and site_reviewer. Users added to the system_admin group has the role system_admin that has permissions to create users, create site, add users to groups, etc. Users added to any of the default groups has permissions for all sites created in Studio.

  2. Site membership of a user is now determined by a mapping of group membership to roles within a site using the mapping file role-mappings.xml (see Role Mappings on how to configure the role mappings). Note the new default groups when you create a site as noted above, these are automatically mapped to roles when using the built-in blueprints.

    When upgrading a site, the default groups in the site are updated as follows:

    3.0 Default Groups ==>
    3.1 Default Groups

    For example, if user john is a member of group Developer (one of the default groups) in the site mysite, after upgrading, user john will be a member of group mysite_developer.

  3. The LDAP authentication configuration has been updated. The attribute siteId has been removed and is no longer needed since site membership of a user is now determined by group membership. Please see Configure LDAP Authentication for the updated configuration.

  4. The headers based authentication configuration has been updated. The groups header value should just be a comma separated list of groups that a user belongs to. In the previous version, 3.0.x, the groups header value contained a comma separated list of sites and groups. Please update the groups header value of users to contain only a comma separated list of groups the user belongs to. Please see Configure Headers Based Authentication for the updated configuration.

  5. After upgrading your Crafter CMS install, you will need to update some site configurations depending on the previous version you were running.

After upgrading your Crafter CMS install, update the following site configurations depending on the previous version you were running:

Sample files

It is possible to copy all the sample files from any of the included blueprints, for example from $CRAFTER_HOME/crafter-authoring/data/repos/global/blueprints/empty/config/studio/administration/samples into your site /config/studio/administration/samples.

Adding the version file

Starting with version 3.1.0 Crafter CMS will use a special file studio_version.xml to track the version of each site and automatically apply upgrades for future releases. When migrating a site from any previous version this file has to be added and committed in the site repository.

<?xml version="1.0" encoding="UTF-8"?>


If your site is heavily customized and you would like to prevent Crafter CMS from trying to upgrade it in the future you can set the version value to any random string, for example <version>DISABLED</version>.

Upgrading Site Configurations


Some of the changes may not be needed depending on the Crafter CMS version in which your site was created.

All files in the folder /config/studio/search/ are no longer used it can be completely removed.

To add the dependency resolver configuration file in the SiteConfig configuration file config-list.xml, add the following:

  <title>Dependency Resolver Configuration</title>
  <description>Dependency Resolver Configuration</description>

In your site-config-tools.xml configuration file, you will need to remove the groups tool, then add the repositories tool. /config/studio/administration/site-config-tools.xml

Remove the groups tool


Add the repositories tool

  <label>Remote Repositories</label>

In your dependency resolver configuration file /config/studio/dependency/resolver-config.xml, replace the following regular expressions:

  • <find-regex>/static-assets/([^&lt;"'\)]+)</find-regex> with <find-regex>/static-assets/([^&lt;"'\)\?]+)</find-regex>

  • <path-pattern>/static-assets/([^&lt;"'\)]+)</path-pattern> with
  • <find-regex>/templates/([^&lt;"]+)\.ftl</find-regex> with


Add the published repository configuration


Remove the following property


Managed configuration files

Starting in version 3.1.0 Crafter CMS will also track an individual version for some configurations files in order to keep them up to date.


These upgrades can also be disabled by setting the version to a random string, just like the site version.


If one of the files do not contain a version tag then all existing upgrades will be applied.

This is the list of files currently managed by Crafter CMS:

  • /config/studio/role-mappings-config.xml
    Current version: 2. In 3.0.x groups were handled by site and starting in 3.1.0 they became global, during the database upgrade existing groups will be renamed to {site}_{role} and this file needs to match.
  • /config/studio/administration/config-list.xml
    Current version: 3. There are new configuration files for URL Rewrite and WebDAV Profiles.
  • /config/studio/administration/site-config-tools.xml
    Current version: 2. There are new datasources for WebDAV file management.

If you are certain that one of those files is already up to date in your site, you can add the version tag with the latest value to prevent the upgrades from being applied to it.