Migration guide for system administrators

This topic lists changes that system administrators should be aware of in Jahia 8. Please review the changes carefully. We also strongly encourage you to read the Migration guide for functional administrators and Migration guide for developers pages.

Permission changes

This section describes permission that have been renamed in Jahia 8, obsolete permissions that have been removed, and permissions that are new to Jahia 8.

Replacement of permissions

To better correspond with the new interfaces, we have introduced new permissions as replacement of ones used with Jahia 7.3. The:

• jContent permission replaces the Edit mode permission
• Page Composer access and jContent access replace the editModeAccess and contributeModeAccess permissions
  When set on an edit role on the current site
  •  Page Composer access grants access to Page Composer
  • jContent access grants access to jContent
• jContentActions permission replaces the editModeActions permission
  Note that Jahia 8.0.3 introduces additional jContentActions permissions. Learn about these permissions in the Migration guide for functional administrators.

Note that these replacements are handled during the Jahia upgrade and do not require any change on your side. The roles who had the old permissions are automatically granted the new ones.

Compatibility

For compatibility purposes, we have moved replaced permissions into a legacy section available in the Other permissions tab in Content Editor, but not removed them. We have also moved obsolete permissions, contributeMode and editSelector,  that are not used anymore.

If these permissions were set on a role in 7.3 they will still be set on the same role in Jahia 8. If you were relying on these permissions in your own modules, you do not have to update your own code as the permissions still exist and are still granted to the same roles.

We encourage you, if you have the opportunity, to update your code to use the new permissions.

Removed permissions

We have removed the permissions related to the legacy managers as these were already deprecated with Jahia 7.3.1.0:

• Editorial content manager
• File manager
• Site manager

New permissions

clearLock

A new Remove locks on contents (clearLock) permission has been added. It allows a user to remove a lock on a node using the context menu, even if the user is not the owner of the lock. This permission is available by default to server administrators, who can then grant it to other roles. To do so, they need to set it on Permissions on current site>Other permissions>Remove locks on contents.

Note: Use the removing locks feature with caution. Always verify the owner of the lock first, as it is not recommended to remove the lock when the corresponding content is part of a publication workflow.

Advanced Options tab

The Advanced Option tab of Content Editor is protected by the Can see advanced options tab permission. This permission is granted by default to the following roles:

• Editor in chief
• Site administrator
• Server administrator

This permission needs to be set at node level (select Permissions on current node when editing a role) to be effective. You can find it in Other permissions under Content Editor.

For more information about permissions required by Content Editor, see About Content Editor permissions.

jExperience

If you are using jExperience, you will need to upgrade it to jExperience 1.12 as jExperience 1.11 is not compatible with Jahia 8. This upgrade to jExperience 1.12 also requires an upgrade from Elasticsearch 5 to 7.

For more information about upgrade jExperience, see Upgrading to jExperience 1.12.

Forms

Jahia 8 only supports Forms 3.0 and higher. When you upgrade to Forms 3.0 and higher, the migration process depends on the version that you are upgrading from:

• Upgrading from Jahia 7.3 and Form Factory
  Form Factory 2.3 is not compatible with Jahia 8 and must be upgraded before you migrate from Jahia 7.3 to 8. If you were on Form Factory, you must first migrate to Forms while still running Jahia 7.3. See Upgrading to Forms 2.4 and higher. Once you have migrated to Forms 2.4 on your Jahia 7.3 environment, then you can migrate to Jahia to 8.
• Upgrading from Jahia 8.0 and Forms 2.4
  To migrate from Forms 2.4 to Forms 3.0 on Jahia 8, you need only to update the modules you are using from Forms in your digital-factory-data/modules folder. Remove the older versions and copy the new ones. See step 4 in the Jahia How to upgrade guide, which explains how to run the Jahia fix applier.

All new versions are available on the Jahia Store for download to prepare your migration.

/jahia prefix for backoffice UI

We are introducing /jahia as prefix for our backoffice URLs (new navigation). If you are blocking such backoffice URLs or if you have custom rewrite rules, we advise you to verify your configurations and update them if needed.

Global mount points are not displayed in contribution interfaces

For information on why global mount points do not display in contribution interfaces, see the corresponding section in the Functional administrators migration guide.

Note that you can still create global mount points if you are using them for more technical integrations. These mount points can be accessed from the Repository Explorer. When editing content in Content Editor, they can be accessed when using the legacy interfaces in the Advanced options tab.

End of support for portlets

Deprecation in Jahia 8.0 and 8.1

Portlets can still be used in Jahia 8.0 and 8.1

• If you are not using portlets, you should revoke the permission for your editors to add portlet references
• If you are using portlets, you must deploy the Portlet module to make the portlet screen visible in Jahia. In your modules, define a route to display Portlet Manager in your site, either in the Administration>Sites accordion or in jContent>Additional. Here is an example of route declaration where edccb972-243e-4564-92e0-c0756891b8b3 is the site node UUID.

  window.jahia.i18n.loadNamespaces('portletsite');
   
  window.jahia.uiExtender.registry.add('adminRoute', 'portletsite', {
      targets: ['jcontent:40'],
      label: 'portletsite:label.title',
      isSelectable: true,
      iframeUrl: window.contextJsParameters.contextPath + '/engines/manager.jsp?conf=portletmanager-anthracite&lang=en&site=edcytcrhcb972-243e-4564-92e0-c0756891b8b3'
  });
  

Identifying a cluster node in the backoffice UI

In Jahia 8, you can display the name of a node/environment in the expanded main menu. A diamond displays over the burger icon to indicate that a name has been provided. You can set this name per node (or use the same name on all the nodes of an environment), by adding the following property on each node:

jahia.environment = Preproduction

where Preproduction is the name of the node

Access to the /tools section

Prior to Jahia 8.0.1.0, users accessed the /tools section with the Jahia Tool Manager user. We removed the Jahia Tool Manager user for security reasons, as administrators had to share this username and password with others. Now Jahia users access the /tools section when they are granted the new System tools access permission. This permission is only available to a new category of roles named System roles and is granted to the new default System administrator role. The root user is the only user who can add users to system roles. In other words, only root can grant a user access to the /tools section by adding them to the System administrator role.

Things to consider when upgrading to Jahia 8.0.1.0:

• Assign the System administrator role to users in your organization that require access to the /tools section
• If you are calling pages from the /tools section in your scripts, you will have to either:
  • update your scripts with the username and password of a user who has access to /tools through membership in the System administrator system role
  • create a new user in Jahia with the same username and password as the previous Jahia Tool Manager user

For more information on using the new System administrator role, see Managing roles and permissions.

Upgrading Jahia OAuth modules

There are several changes to the new Jahia OAuth modules that are compatible with Jahia 8.0.1.

• The Jahia OAuth module in 8.0.1 replaces the individual connector modules in version 7 and includes the FranceConnect and Google OAuth connectors. The Facebook and LinkedIn connectors are not yet available for Jahia 8, but will be included in a future version of the Jahia OAuth.
• In the new modules, only mapping settings have changed. Other configuration settings remain the same and should be familiar to you.
• You do not need to change the social login forms and components that you use in your template sets.
• When you upgrade from Jahia 7 to Jahia 8, you need to uninstall the old modules, then add and configure the new modules.

Jahia 8.0.1 supports the following modules:

• Jahia Authentication 1.1
  The backbone of SSO solutions that enables you to manage open authentication on your site.
• Jahia OAuth 3.0
  The OAuth connectors. This module replaces the individual version 7 connector modules, meaning that this module includes the FranceConnect and Google OAuth connectors and future versions will include the Facebook and LinkedIn connector modules.
• JCR Authentication provider 3.0 
  Provides authentication to Jahia and lets you map visitor attributes from the connectors to Jahia user attributes.
• jExperience OAuth data mapper 1.12
  Enables you to map visitor attributes from the Oauth connectors to jExperience visitors profiles.

For information on configuring the new modules after the upgrade, see Configuring OAuth modules and social login.

Remote publication

If you are using a Remote Publication environment, and after the upgrade of all the servers in version 8, you will need to re-activate, for each site on each remote server, the available languages for the site.

This can be done by executing the following GraphQL query from the tools interface on the remote server:

mutation {
  jcr {
    mutateNode(pathOrId:"/sites/siteKey") {
      mutateProperty(name: "j:languages") {
        addValues(values:["en", "fr", "de"])
      }
    }
  }
} 

You need to replace siteKey with the site key of your site. In  addValues, you need to provide the exhausitve list of languages to use on the remote site.

This step is necessary, otherwise the site may not be available for the given languages on the remote server.