# Internal Cascade API changelog

> New methods added to existing Cascade API objects New com.hannonhill.cascade.apl.asset.common.PermissionLevel enum added with values NONE, READ and WRITE New methods added to com.hannonhill.cascade.apl.asset.home.PermissionsCapableAsset getAllPermissionLevel() - returns the PermissionLevel&#160

URL: https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/internal-cascade-api/internal-cascade-api-changelog.html
category: Developing in Cascade
article-type: reference
content-kind: article
release-availability: all
tags: api
updated: 2026-10-06

## Cascade CMS 8.25

### New methods added to existing Cascade API objects

- New `com.hannonhill.cascade.apl.asset.common.PermissionLevel` enum added with values `NONE`, `READ` and `WRITE`
- New methods added to `com.hannonhill.cascade.apl.asset.home.PermissionsCapableAsset`
    - `getAllPermissionLevel()` - returns the `PermissionLevel` applied to all users that do not have an explicit ACL entry
    - `setAllPermissionLevel(PermissionLevel)` - updates the `PermissionLevel` for the asset
    - `addReadAccessUser(String)` - adds an explicit READ permission for the given user name
    - `addWriteAccessUser(String)` - adds an explicit WRITE permission for the given user name
    - `addReadAccessGroup(String)` - adds an explicit READ permission for the given group name
    - `addWriteAccessGroup(String)` - adds an explicit WRITE permission for the given group name
    - `clearPermissions()` - Clears explicit ACL entries and sets all permission level to NONE
- New methods added to `com.hannonhill.cascade.api.asset.common.StructuredDataNode` for consistency with `DynamicMetadataField`:
    - `getValue()`
    - `getValues()`
    - `hasValue(String)`

## Cascade CMS 8.22

### New Query API methods

- [$_.query().byDataDefinition](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#__query_byDataDefinition)
- [$_.query().bySiteName](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#__query_bySiteName)
- [$_.query().byFolderPath](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#__query_byFolderPath)
- [$_.query().hasAnyPaths](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#__query_hasAnyPaths)
- [$_.query().hasStructuredData](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#__query_hasStructuredData)
- [$_.query().hasAnyStructuredDataValues](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#__query_hasAnyStructuredDataValues)
- [$_.query().hasStructuredDataByFieldId](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#__query_hasStructuredDataByFieldId)
- [$_.query().hasAnyStructuredDataValuesByFieldId](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#__query_hasAnyStructuredDataValuesByFieldId)
- [$_.query().preloadDynamicMetadata](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#__query_preloadDynamicMetadata)
- [$_.query().preloadStructuredData](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#__query_preloadStructuredData)

## Cascade cloud v20220802

### New methods added to existing Cascade API objects

- New methods added to `com.hannonhill.cascade.api.asset.home.StructuredDataCapableAsset`
    - `getStructuredDataNodeWithFieldId()` - returns the first found `StructuredDataNode` that matches given `field-id`
    - `getStructuredDataNodesWithFieldId()` - returns a `List<StructuredDataNode>` of `StructuredDataNode` objects that match given `field-id`
- New methods added to `com.hannonhill.cascade.api.asset.common.StructuredDataNode`
    - `getChildWithFieldId()` - returns the first found child `StructuredDataNode` that matches given `field-id`
    - `getChildrenWithFieldId()` - returns a `List<StructuredDataNode>` of child `StructuredDataNode` objects that match given `field-id`
    - `getDefinitionFieldId()` - returns the `field-id` for the `StructuredDataNode`

## Cascade CMS 8.16

### New Cascade API objects

- `com.hannonhill.cascade.api.asset.admin.ContentType` - represents a Content Type asset
    - This object inherits all methods from `SiteManagementAreaAsset`
- `com.hannonhill.cascade.api.asset.admin.MetadataSet` - represents a Metadata Set asset
    - This object inherits all methods from `SiteManagementAreaAsset`
- `com.hannonhill.cascade.api.asset.admin.StructuredDataDefinition` - represents a Data Definition asset
    - This object inherits all methods from `SiteManagementAreaAsset`
- `com.hannonhill.cascade.api.asset.common.FieldItem` - contains the `label` and `value` information of an individual item that can be selected for a given checkbox, radio, dropdown or multiselect Dynamic Metadata or Structured Data field. If no label is present, the value will be used as the field item's label.
- `com.hannonhill.cascade.api.asset.common.ImageDimensions` - contains the width and height (in pixels) for an image file

### New methods added to existing Cascade API objects

- New methods added to `com.hannonhill.cascade.api.asset.home.Page`
    - `getDataDefinition()` - returns `com.hannonhill.cascade.api.asset.admin.StructuredDataDefinition`, which is the Data Definition associated with the Page
    - `getContentType()` - returns `com.hannonhill.cascade.api.asset.admin.ContentType`, which is the Content Type associated with the Page
- New method added to `com.hannonhill.cascade.api.asset.home.XHTMLDataDefinitionBlock`
    - `getDataDefinition()` - returns `com.hannonhill.cascade.api.asset.admin.StructuredDataDefinition`, which is the Data Definition associated with the Block
- New method added to `com.hannonhill.cascade.api.asset.home.MetadataAwareAsset`
    - `getMetadataSet()` - returns `com.hannonhill.cascade.api.asset.admin.MetadataSet`, which is the Metadata Set associated with the asset
- New method added to `com.hannonhill.cascade.api.asset.home.File`
    - `getImageDimensions()` - returns `com.hannonhill.cascade.api.asset.common.ImageDimensions`, which are the dimentions of an image file, if present
- `DynamicMetadataField.getPossibleFieldItems()` and `StructuredDataNode.getPossibleFieldItems()` returns a `List<FieldItem>` of all possible field items that can be selected for a given checkbox, radio, dropdown or multiselect field. An empty list will be returned for fields that do not support selecting field items.
- `DynamicMetadataField.getSelectedFieldItems()` and `StructuredDataNode.getSelectedFieldItems()` returns a `List<FieldItem>` of all selected field items for a given checkbox, radio, dropdown or multiselect field. An empty list will be returned for fields that do not support selecting field items.
    - Note: dropdowns that allow custom values will return a field item which uses the custom value as its `label` and `value`.
- Added `StructuredDataNode.getLabel()` to access the label of a given Structured Data field.

### New Locator Tool methods

- `locateFormat(String path, String siteName)` and `locateFormat(String path)` - returns a Format at the given path and in the given site (optional).
- `locateLinkable(String path, String siteName)` and `locateLinkable(String path)` - returns a Page, File, External Link, or Block at the given path and in the given site (optional).

### Improvements

- When working with API objects, metadata and dynamic metadata fields will be cached after loading to improve rendering time during operations such as sorting on dynamic metadata values.

## Cascade CMS 8.13

### Fixed

- The `TextBlockAPIAdapter.getText` method will no longer return a wrapping `<​system-xml>` element with the Block's text content.

## Cascade CMS 8.12

### Improvements

- Consecutive calls with `structuredData`, `getStructuredDataNode()`, or `getStructuredDataNodes()` will now be cached to improve rendering times.

### Removed

- `StructuredDataNode.identifier.id` will no longer return an `id` for `group` elements.

## Cascade CMS 8.11

### New Cascade API methods

- `DynamicMetadataField.hasValue(String)` - checks if the given value is within the selected values.
- `DynamicMetadataField.isDatetime()` - returns `true` if the field is a date-time field.

## Cascade CMS 8.9

### New Cascade API methods:

- `FolderContainedAsset.getTags()` - Returns a list of Strings that are tag names assigned to given asset.
    - Velocity example: `#set($pageTags = $page.tags)`.
- `Site.getAvailableTags()` - Returns a list of Strings that are tags available in given site, which includes system level tags. The resulting list has unique values and #is sorted alphabetically.
    - Velocity example: `#set($allTags = $page.site.availableTags)`

### New Query API methods:

- `hasAnyTags(['tag1', 'tag2'])` - Limits the search results to assets that have at least one of given tags
- `hasTag('tag')` - Same as calling `hasAnyTags(['tag'])`
- `hasAnyMetadataValues(String fieldName, Collection<String> fieldValues)` - Same as calling the existing `hasMetadata(String fieldName, Collection<String> fieldValues)`, but the method name has been updated to be more clear about the method is doing (similar to `hasAnyTags`).
    - Deprecated: `hasMetadata(fieldName, values)`
- The `toString()` method for Query API with the information about tags
- The hard max limit on Query API returned assets has been **increased from 500 to 2,000** to help with use cases where 500 assets was not enough.
    - A note about performance: tests have shown that fetching 2,000 assets takes ~2 times longer than fetching 400 assets.

### Other improvements

- The `FolderContainedAsset.getLinkingAssets()` method will now return assets linked through Data Definition chooser fields

## Cascade CMS 8.7

`Site` asset has 3 new methods:

- `getNamingRuleCase()`
- `getNamingRuleSpacing()`
- `getNamingRuleAssets()`

These methods return effective naming rules inside of that site. This means that if the `Site` inherits naming rules, the system-wide naming rules will be returned.

Also, a new method `transform()` has been added to `FilenameNormalizer` that transforms given asset's name based on the naming rules inside of the asset's site.

```xml
systemName = utilityProvider.getFilenameNormalizer().transform(asset, systemName);
```

## Cascade CMS 8.6

### Improvements

- Added a new method `StructuredDataNode.hasTextValue(String)` that checks if the given value is within the selected values.

### Fixed

- `StructuredDataNode.getTextValues()` no longer returns an extra empty value.

## Cascade CMS 8.1.1

### New methods exposed on objects

Asset now expose a label property `$asset.label` that returns Display Name, Title, or the asset's system name -- whichever is populated first. This is convenience method for quickly accessing this information.

## 8.0.2

### New API objects

- New API object` com.hannonhill.cascade.api.asset.admin.Site` that represents a Site asset
    - This object inherits all methods from `PermissionsCapableAsset`
    - In addition to these methods, it has `getUrl``()` method that returns String URL of the Site.
- New class that API objects inherit from `com.hannonhill.cascade.api.asset.admin.SiteManagementAreaAsset`
    - This class inherits from com.hannonhill.cascade.api.asset.common.PermissionsCapableAsset
    - It contains method getSite() which returns` com.hannonhill.cascade.api.asset.admin.Site,` which is a Site in which the asset is located.
- API objects that now inherit from `com.hannonhill.cascade.api.asset.admin.SiteManagementAreaAsset`:
    - `com.hannonhill.cascade.api.asset.admin.DestinationContainer`
    - `com.hannonhill.cascade.api.asset.admin.Transport`
    - `com.hannonhill.cascade.api.asset.admin.Destination`
    - `com.hannonhill.cascade.api.asset.admin.AssetFactory`

### New methods in existing API objects

- New method in` com.hannonhill.cascade.webservice.schema.FolderContainedAsset`
    - `getSite() `- returns` com.hannonhill.cascade.api.asset.admin.Site,` which is a Site in which the asset is located.
- New method in `com.hannonhill.cascade.api.asset.common.BaseAsset`
    - `getAssetType``()` - returns a String that represents the type of the current asset, equivalent to calling `getIdentifer().getType().toString()`
- New method in `com.hannonhill.cascade.api.asset.home.Block`
    - `getBlockType``()` - returns a String that represents type of the block
- New method in `com.hannonhill.cascade.api.asset.home.Format`
    - `getFormatType()` - returns a String that represents type of the format
- New method in `com.hannonhill.cascade.api.asset.home.MetadataAwareAsset`
    - `getLinkingAssets()` - returns a List of `com.hannonhill.cascade.api.asset.home.FolderContainedAssets`that contain links to this asset in their content through "system-asset" links, links in XML/XHTML and data definition chooser fields.

### Removed objects and methods

- Removed API object `com.hannonhill.cascade.api.asset.admin.Target`
- Removed methods from `com.cms.publish.PublishTriggerInformation`
    - `getTargetId()`
    - `setTargetId(String targetId)`
    - `getTargetPath()`
    - `setTargetPath(String targetPath)`

## 8.0

### Improvements

- StructuredDataNode.getAsset() will now return null if the node's assigned asset is recycled.
- Added FeedBlock.getFeedAsXMLElement(),which will return the feed content as a JDOM Element. This Element will always refer to a "system-xml" element that wraps the content of the feed itself. This is a convenience method which allows the feed content to be traversed in a DOM structure as opposed to a String.

## 7.8

### Fixed

- Fixed File.getData() so that it doesn't throw LazyInitializationException ([CSI-680](https://hannonhill.jira.com/browse/CSI-680))
- Fixed File.getData().getSize() so that it returns real size instead of "0" ([CSI-681](https://hannonhill.jira.com/browse/CSI-681))

### Improvements

- Added File.getText() to get content of File as UTF8 string ([CSI-682](https://hannonhill.jira.com/browse/CSI-682))
- Added support for root-relative XPath expressions (e.g. /path/to/element) for XML returned from "get...AsXMLElement" API methods ([CSI-683](https://hannonhill.jira.com/browse/CSI-683))
- Added File.getFileSize() that works just as File.getData().getSize() but returns results much quicker because it does not need fetch the data

## 7.6

### New API methods

- com.hannonhill.cascade.api.asset.common.Metadata:
    - getDynamicField(String name): Finds a dynamic metadata field by name
- com.hannonhill.cascade.api.asset.common.DynamicMetadataField:
    - getValue(): Get a single value for the DynamicMetadataField. If the field has more than 1 value, only the first is returned
- com.hannonhill.cascade.api.asset.common.StructuredDataNode:
    - getChildren(): Same as StructuredDataNode.getGroup() but the method name is more in line with the two other methods added to StructuredDataNode
    - getChildren(String identifier): Returns all children of a group StructuredDataNode that match the supplied identifier
    - getChild(String identifier): Returns the first child of a group StructuredDataNode that matches the supplied identifier
- com.hannonhill.cascade.api.asset.home.StructuredDataCapableAsset (com.hannonhill.cascade.api.asset.home.Page and com.hannonhill.cascade.api.asset.home.XHTMLDataDefinitionBlock)
    - getStructuredDataNodes(String path): Finds all StructuredDataNodes that match the supplied path

## 7.4

### New API methods

- com.hannonhill.cascade.api.asset.home.FeedBlock.getFeed() - Will fetch feed contents
- com.hannonhill.cascade.api.asset.home.FolderContainedAsset.getSiteName() - Returns the name of the asset’s site
- com.hannonhill.cascade.api.asset.home.StructuredDataCapableAsset
    - getDefinitionPath() - Returns the Data Definition’s path if Data Definition is assigned
    - getStructuredDataNode(path) - Will return a structured data node by path using group names, for example “address/city” if the Data Definition has a group “address” with a field “city” inside of that group
- com.hannonhill.cascade.api.asset.home.PublishableAsset:
    - getLastPublishedBy() - Returns name of a user who last published the asset
    - getLastPublishedOn() - Returns date when the asset was last published
    - getShouldBeIndexed() - Returns true of the asset is enabled for indexing
    - setIncludeWhenIndexing() - Enabled or disabled the asset for indexing
    - getLink() - Returns a link in the same format as in Index Blocks (site://sitename/path/to/asset)
- com.hannonhill.cascade.api.asset.home.Reference.getReferencedAsset() - Returns the referenced asset
- com.hannonhill.cascade.api.asset.common.StructuredDataNode.getAsset() - Similar to existing getAssetIdentifier() method but this will return the actual asset
- com.hannonhill.cascade.api.asset.common.PermissionsCapableAsset has been added to the hierarchy. The following classes extend it:
    - AssetFactory
    - Destination
    - DestinationContainer
    - FolderContainedAsset
    - Transport
- com.hannonhill.cascade.api.asset.common.PermissionsCapableAsset contains the following methods:
    - isCurrentUserCanRead() - Returns true if current user has read access to the asset
    - isCurrentUserCanWrite() - Returns true if current user has write access to the asset
    - isUserCanRead(username) - Returns true if a user with given username has read access to the asset
    - isUserCanWrite(username) - Returns true if a user with given username has write access to the asset
- com.hannonhill.cascade.api.asset.home.Page.getXHTMLAsXMLElement(), StructuredDataNode.getTextValueAsXMLElement() (WYSIWYG fields only), XHTMLDataDefinitionBlock.getXHTMLAsXMLElement(), XMLBlock.getXMLAsXMLElement() - Returns the same contents as the counterpart methods which do not cantain “AsXMLElement” in their name return, with the difference that these “...AsXMLElement” methods return JDOM Element objects as opposed to Strings. The Element object is always a “system-xml” element whose children are the actual contents. These methods are useful when using the API in a Velocity Format as you can use the XPathTool to filter them.
- com.hannonhill.cascade.api.asset.common.DynamicMetadataField.setValues() - Allows changing values of dynamic metadata fields

### Modifications to existing API methods

- com.hannonhill.cascade.api.asset.common.Page.getXHTML(), StructuredDataNode.getTextValue() (WYSIWYG fields only), XHTMLDataDefinitionBlock.getXHTML(), XMLBlock.getXML() - will return String XML with links rewritten to cross-site links, for example a path in format “/path/to/asset” will be converted to “site://sitename/path/to/asset”
- com.hannonhill.cascade.api.asset.common.MetadataAwareAsset - Dynamic fields will now be compared to metadata set and mapped accordingly. For example, if metadata set gets updated and gets a new field added with default values, then the corresponding MetadataAwareAsset will have the new field with default values populated without the asset having to be manually re-edited. Similarly, if a metadata set gets updates and gets an existing dynamic metadata field removed, then the corresponding MetadataAwareAsset will not have that field anymore without having to re-edit that asset.
- com.hannonhill.cascade.api.asset.common.StructuredDataCapableAsset - Similarly to the above, the structured data fields will be mapped according to the current version of the Data Definition.
- com.hannonhill.cascade.api.asset.common.DynamicMetadataField does not extend NamedAsset anymore

## 7.2.2

- com.hannonhill.cascade.api.asset.home.MetadataAwareAsset: Fixed issue where using getMetadata().getDynamicFields() would cause a NullPointerException when used from within an Asset Factory Plugin [CSI-549](https://hannonhill.jira.com/browse/CSI-549)
- com.hannonhill.cascade.api.asset.common.PathIdentifier: Fixed issue where getPath() returns NULL assets other than pages [CSI-546](https://hannonhill.jira.com/browse/CSI-546)

## 7.2

- com.hannonhill.cascade.api.asset.common.DynamicMetadataField: New isMultiSelect() method has been added which returns true if the dynamic metadata field is a multi-select field. In the past, if the isDropdown() method returned true, then isMultiple() would be called to determine if the field was a multi-select.
- com.hannonhill.cascade.api.asset.common.DynamicMetadataField: The isMultiple() method has been removed.

## 6.8

- com.hannonhill.cascade.api.asset.home.Page: A new method, setXHTML(String xhtml), has been added which allows the XHTML of a Page to be changed via the API.
- com.hannonhill.cascade.api.asset.common.StructuredDataNode: Two new methods have been added: setTextValue(String value) and setTextValues(String[] values). The first method allows the text of a single value StructuredDataNode to be set. The second method allows the text of a multi-value StructuredDataNode to be set (e.g. a multi-select or checkbox StructuredDataNode).
- com.hannonhill.cascade.api.asset.common.DynamicMetadataField: A new method, setValue(String value), has been added which allows the value of a DynamicMetadataField to be changed via the API. This only supports single value DynamicMetadataFields.
- com.hannonhill.cascade.api.operation.Create: A new method, newAPIAsset(BaseAsset asset), has been added to aid with creation of assets in Asset Factory Plugins. This method will take an existing asset and create a new object using the properties that exist on the existing asset. This ensures that all required properties are populated on a new API object so that it can successfully be created using the Create operation.

## 6.7.3

- For Publish operation, changed setMode() and getMode() methods to accept and return a String object with following possible values: Publish.MODE_PUBLISH and Publish.MODE_UNPUBLISH.

## 6.7

- com.hannonhill.cascade.api.asset.home.FolderContainedAsset - two new methods: setHideSystemName and isHideSystemName. This is used to hide the System Name field on creation with an Asset Factory Plugin.
    - See com.cms.assetfactory.DisplayToSystemNamePlugin#doPluginActionPre() for an example of how this change is used.
- com.hannonhill.cascade.api.adapters.XHTMLBlockAPIAdapter is now com.hannonhill.cascade.api.adapters.XHTMLDataDefinitionBlockAPIAdapter
- com.hannonhill.cascade.api.asset.home.XHTMLBlock is now com.hannonhill.cascade.api.asset.home.XHTMLDataDefinitionBlock

## 5.7.2

- Added the isUnpublish() method to the PublishTriggerInformation object which indicates whether or not the current job is marked as an un-publish

## 5.7

- Renamed com.hannonhill.cascade.model.dom.identifier.home.StylesheetIdentifier to com.hannonhill.cascade.model.dom.identifier.home.FormatIdentifier
- Added com.hannonhill.cascade.api.asset.home.Format
- Added com.hannonhill.cascade.api.asset.home.ScriptFormat
- Both com.hannonhill.cascade.api.asset.home.XSLTFormats and com.hannonhill.cascade.api.asset.home.ScriptFormats use the com.hannonhill.cascade.model.dom.identifier.home.FormatIdentifier
- Renamed com.hannonhill.cascade.api.asset.home.Stylesheet to com.hannonhill.cascade.api.asset.home.XSLTFormat