Breaking Changes in CrafterCMS 4

This section covers changes that might affect your CrafterCMS projects, as well as other considerations before upgrading. Please review the following and apply changes as required:

  • CrafterCMS requires Java 21.
    See Requirements for more information on CrafterCMS requirements.

  • CrafterCMS now uses Jakarta EE.
    The jakarta.* namespace is now used instead of javax.*. To update your project, find and replace javax with jakarta in your Groovy code or Java if you are bringing in jars with Grab.

  • CrafterCMS has upgraded the AWS client library to version 2.
    This may contain breaking changes that impact custom Java and Groovy code. See https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration.html for more information on the changes in the library that may affect your project/s.

Breaking Changes in CrafterCMS 4.7.0

  • Crafter Social and Crafter Profile are not included in CrafterCMS Community Edition. They remain available in CrafterCMS Enterprise.

  • New basic users.properties file to support Engine authentication. Define Engine users in this new file. Remember that roles in the file must match the roles used by the site’s security rules or authorizedRoles. Users in the file are Engine users only.

    Community Edition projects that used Crafter Profile for Engine authentication must migrate the required users and roles to users.properties.

    See Engine Properties-Based Authentication for more information.

  • Preview tokens now use a dedicated encryption configuration and token format. Preview tokens created before 4.7.0 are no longer valid and must be regenerated.

    Before upgrading, configure matching CRAFTER_PREVIEW_TOKEN_KEY and CRAFTER_PREVIEW_TOKEN_SALT values for Studio and Engine, replacing the defaults. See Preview Token Encryption for more information.

  • Deployer target management APIs no longer accept the management token in the token query parameter. Update clients that create, read, deploy, duplicate, unlock, reindex, or delete targets to send the configured deployer.main.management.authorizationToken value in the X-Crafter-Management-Token request header. Deployer monitoring APIs continue to use the token query parameter.

  • Crafter Profile Enterprise only feature now uses configurable access tokens.

    A new local Authoring installation with no MongoDB data generates PROFILE_ADMIN_ACCESS_TOKEN_ID, PROFILE_ENGINE_ACCESS_TOKEN_ID, and PROFILE_SOCIAL_ACCESS_TOKEN_ID, then stores them in $CRAFTER_DATA_DIR/profile/access-tokens.env. Profile, Engine, and Social read those values. All three environment variables must be set or unset. A new installation that uses a remote MongoDB host does not create this file and stops until the three IDs are supplied.

    An upgrade with existing local MongoDB data, or an installation using a remote MongoDB host, stops during Authoring startup until all three access token IDs are configured. When MongoDB already contains access tokens, the configured access token IDs must match those tokens. When the access token collection is empty, Profile seeds the configured IDs and rejects the former default IDs. Delivery does not generate its own token file: copy Authoring’s access-tokens.env to each Delivery node, or set the same three variables from the secret store used to seed Profile. Installations that do not deploy Profile skip this setup.

    See Profile Access Tokens for the variables, and Upgrade Notes for CrafterCMS 4.7.0 for the configuration required when an existing installation still uses the 4.6.x default tokens.

Breaking Changes in CrafterCMS 4.6.0

  • Groovy, Freemarker, or other Engine code that called siteItemService.getSiteItem(url) or getSiteTree(...) for paths outside the allowed descriptor patterns now receives null or an empty tree. To include extra descriptor locations, extend:

    crafter.engine.site.default.descriptors.allowed.paths=/site/.*

    See Allowed Descriptor Paths for more information.

  • Use siteItemService.exists(path) when you only need to know if a path exists. That check is not limited by the allowed-path patterns.

  • Search clients that send a script key (or any key matching crafter.engine.search.restricted.key.patterns) in the JSON body will get 400 Bad Request.

    See Search Restricted Key Patterns for more information

  • Users without Publish permission on a related item will no longer see that item in the publish soft-dependency list.

  • Engine REST Scripts No Longer Produce XML.

    Clients that request XML via the Accept: application/xml header or a .xml URL will receive HTTP 406 Not Acceptable. Update those clients to request JSON (Accept: application/json or a .json URL) and parse JSON instead of XML.

Breaking Changes in CrafterCMS 4.5.2

  • Engine no longer bundles the following Groovy modules: groovy-json, groovy-xml, groovy-yaml, groovy-templates, groovy-datetime, groovy-nio, groovy-servlet, groovy-jsr223, groovy-macro, groovy-ant, groovy-cli-picocli, groovy-console, groovy-docgenerator, groovy-groovydoc, groovy-groovysh, groovy-jmx, groovy-swing, groovy-test, and groovy-test-junit5.

    Scripts that use classes from those modules above, including groovy.json.JsonSlurper, groovy.json.JsonOutput, and groovy.xml.XmlUtil, will fail at runtime.

    Update your Groovy scripts to @Grab the required modules like below:

    @Grab(group='org.apache.groovy', module='groovy-json', version='4.0.33', initClass=false)
@Grab(group='org.apache.groovy', module='groovy-xml', version='4.0.33', initClass=false)

    Note that Crafter Engine disables Grape downloads by default and only makes previously downloaded grapes available. See Grapes Download for more information on downloading Groovy dependencies for scripts.

  • Engine and Studio with request-body endpoints that use the XML converter are are now restricted to application/json.

    Clients with request-body endpoints that use the XML converter must convert the request body to JSON and set the Content-Type header to application/json. Requests using an unsupported content type will receive HTTP 415 Unsupported Media Type.

Breaking Changes in CrafterCMS 4.5.1

Starting version 4.5.1, the version information and system information for Studio, Engine and Deployer are now separate. Use the following monitoring APIs for retrieving version or system information:

Module

Get version information

Get system information

Studio

/api/2/monitoring/version

/api/2/monitoring/sysinfo

Engine

/api/1/monitoring/version.json

/api/1/monitoring/sysinfo.json

Deployer

/api/1/monitoring/version

/api/1/monitoring/sysinfo

Breaking Changes in CrafterCMS 4.5.0

  • OpenSearch 3 has removed the _toQuery() method from the QueryVariant interface. QueryVariant is the base for Query variants, e.g.: BoolQuery, FuzzyQuery, MatchQuery, etc.

    Search-related Groovy scripts might need to be updated to use toQuery() instead. Below is an example of a query that will need to be updated:

    Sample OpenSearch 2.x _toQuery() method that needs to be updated
    SearchRequest request = SearchRequest.of(r -> r
                  .query(query.build()._toQuery())
                  .from(start)
                  .size(rows)
                  .highlight(highlighter.build())
          )

    Here’s the updated query:

    Updated query with OpenSearch 3.x toQuery() method
    SearchRequest request = SearchRequest.of(r -> r
                  .query(query.build().toQuery())
                  .from(start)
                  .size(rows)
                  .highlight(highlighter.build())
          )

  • Automatic grapes download for scripts (@grab) is disabled by default.

    See Studio, Engine and Deployer grapes configuration for more information on enabling automatic grapes download.

Breaking Changes in CrafterCMS 4.4.3

CrafterCMS version 4.4.3 works with JavaScript SDK version 5.0.0 and later. See Compatibility with CrafterCMS Version for more information.

Breaking Changes in CrafterCMS 4.4.0

Spring Boot 3.5 has updated the profile naming rules. Only dash( - ), underscore( _ ), letters and digits are allowed now. We are updating spring profile names across CrafterCMS to comply with the new rules. So far only Deployer (the one using spring boot) would be affected. However, for consistency, we are updating all profiles even if not related to the Deployer

Here’s the list of updated spring profile names:

Old Profile Name

New Profile Name

crafter.studio.dbClusterPrimaryReplica

crafter_studio_dbClusterPrimaryReplica

crafter.studio.externalDb

crafter_studio_externalDb

crafter.studio.samlSecurity

crafter_studio_samlSecurity

crafter.engine.samlSecurity

crafter_engine_samlSecurity

crafter.core.applicationCache

crafter_core_applicationCache

If you are using any of the old profile names listed above, admins will need to update the configuration overrides to use the new profile names. These are usually configured in the crafter-setenv.sh file located under the CRAFTER_HOME/bin/ folder.

Breaking Changes in CrafterCMS 4.3.0

Breaking Changes in CrafterCMS 4.2.2

CrafterCMS uses TinyMCE version 7 for the RTE control. The following properties were removed from the RTE control in CrafterCMS version 4.2.2:

  • Force Root Block p Tag

    This property uses the forced_root_block option in TinyMCE to set it to a true/false value. Starting in TinyMCE version 6, this option no-longer accepts the false value or an empty string value. Setting forced_root_block to false is not compatible with Real-time Collaboration and also blocks various editor functions from working correctly and causes non-semantic HTML to be generated. Newer options are now available for handling line breaks and paragraphs, like the newline_behavior.

  • Force br New Lines

    This property uses the force_br_newlines option in TinyMCE version 3 and 4. Starting with TinyMCE 5.x, the handling of line breaks and paragraphs became more standardized, and newer options like newline_behavior were introduced to provide greater flexibility for managing line breaks. The force_br_newlines option is no longer actively recommended in newer versions due to potential issues with content formatting and compatibility with modern HTML standards, hence the removal of the Force br New Lines property.

To customise the new behaviours mentioned above, use the TinyMCE config in the User Interface Configuration ui.xml

Breaking Changes in CrafterCMS 4.2.0

The following APIs are removed from CrafterCMS 4.1 to 4.2:

  • /api/1/services/api/1/publish/publish-items.json

  • /api/1/services/api/1/publish/reset-staging.json

  • /api/1/services/api/1/dependency/calculate-dependencies.json

  • /api/1/services/api/1/content/content-exists.json

Below are the APIs that are now removed from CrafterCMS 4.2. Note that most of the APIs in the list has been deprecated in previous versions:

API

URL

New API

Clear Configuration Cache

/api/1/services/api/1/site/clear-configuration-cache.json

clearConfigurationCache

Get Available Blueprints

/api/1/services/api/1/site/get-available-blueprints.json

availableBlueprints

Get Configuration

/api/1/services/api/1/site/get-configuration.json

getConfiguration

Write Configuration

/api/1/services/api/1/site/write-configuration.json

writeConfiguration

Add Remote

/api/1/services/api/1/repo/add-remote.json

addRemoteRepository

List Remote Repositories

/api/1/services/api/1/repo/list-remote.json

listRemoteRepositories

Pull From Remote

/api/1/services/api/1/repo/pull-from-remote.json

pullFromRemoteRepository

Push To Remote

/api/1/services/api/1/repo/push-to-remote.json

pushToRemoteRepository

Rebuild Database

/api/1/services/api/1/repo/rebuild-database.json

syncFromRepo

Remove Remote

/api/1/services/api/1/repo/remove-remote.json

removeRemoteRepository

Get Audit

/api/1/services/api/1/audit/get.json

getAuditLog

Publish Items

/api/1/services/api/1/publish/publish-items.json

operation/workflowPublish

Publish Status

/api/1/services/api/1/publish/status.json

getPublishingStatus

Reset Staging Publishing Target

/api/1/services/api/1/publish/reset-staging.json

Get dependencies

/api/1/services/api/1/dependency/get-dependencies.json

getSimpleDependencies

Get Deployment History

/api/1/services/api/1/deployment/get-deployment-history.json

getDashboardPublishingHistory

Get Scheduled Items

/api/1/services/api/1/deployment/get-scheduled-items.json

getPublishingScheduled

Crop Image

/api/1/services/api/1/content/crop-image.json

Set Item State

/api/1/services/api/1/content/set-item-state.json

setItemStates

Unlock Content Item

/api/1/services/api/1/content/unlock-content.json

itemUnlockByPath

Content Exists

/api/1/services/api/1/content/content-exists.json

contentExists

Get UI Resource Override

/api/1/services/api/1/server/get-ui-resource-override.json

Transcode

/api/1/services/api/1/aws/elastictranscoder/transcode.json

AWS S3 Upload

/api/1/services/api/1/aws/s3/upload.json

uploadItem

MediaConvert

/api/1/services/api/1/aws/mediaconvert/upload.json

uploadVideo

Get User Activity

/api/1/services/api/1/activity/get-user-activities.json

getDashboardMyActivities

Post Activity

/api/1/services/api/1/activity/post-activity.json

Copy Item

/api/1/services/api/1/clipboard/copy-item.json

Cut Item

/api/1/services/api/1/clipboard/cut-item.json

Get Items

/api/1/services/api/1/clipboard/get-items.json

Paste Item

/api/1/services/api/1/clipboard/paste-item.json

Get User Roles

/api/1/services/api/1/security/get-user-roles.json

getUserSiteRoles

Get user permissions for project/site and space (path)

/api/1/services/api/1/security/get-user-permissions.json

Login

/api/1/services/api/1/security/login.json

Logout

/api/1/services/api/1/security/logout.json

List WebDAV

/api/1/services/api/1/webdav/list.json

Upload to WebDAV

/api/1/services/api/1/webdav/upload.json

Create Jobs

/api/1/services/api/1/workflow/create-jobs.json

workflowCreatePackage

Get Go Live Items

/api/1/services/api/1/workflow/get-go-live-items.json

getDashboardContentPendingApprovalDetail

Get Workflow Affected Paths

/api/1/services/api/1/workflow/get-workflow-affected-paths.json

getWorkflowAffectedPaths

Go Delete

/api/1/services/api/1/workflow/go-delete.json

contentDelete

Go Live

/api/1/services/api/1/workflow/go-live.json

bulkGoLive

Reject

/api/1/services/api/1/workflow/reject.json

workflowReject

Request Publishing

/api/1/services/api/1/workflow/submit-to-go-live.json

workflowRequestPublish

Calculate Dependencies

/api/1/services/api/1/dependency/calculate-dependencies.json

Upgrading 3.1.x Sites

  • MongoDB in Crafter Social and Crafter Profile Enterprise only feature has been updated. To upgrade MongoDB in your installation, see Upgrading MongoDB

  • CrafterCMS 4.1.x onward requires Git.
    See Requirements for more information on CrafterCMS requirements.

  • CrafterCMS 4.1.x onward has a new Studio UI. To get the same Sidebar you’re used to, update the UI Configuration

  • Update ICE to move to XB

  • Studio and Engine SAML configuration now uses a key and certificate for configuration instead of using keystore.
    See Engine SAML2 Configuration and Studio SAML2 Configuration for more information.