Internal Cascade API Changelog

Cascade CMS 8.22

New Query API Methods

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).


  • 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


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

Cascade CMS 8.12


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


  • 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 = $

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. 

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

Cascade CMS 8.6


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


  • 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.


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.FolderContainedAssetsthat 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)



  • 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.



  • Fixed File.getData() so that it doesn't throw LazyInitializationException (CSI-680)
  • Fixed File.getData().getSize() so that it returns real size instead of "0" (CSI-681)


  • Added File.getText() to get content of File as UTF8 string (CSI-682)
  • Added support for root-relative XPath expressions (e.g. /path/to/element) for XML returned from "get...AsXMLElement" API methods (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


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


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


  • 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
  • com.hannonhill.cascade.api.asset.common.PathIdentifier: Fixed issue where getPath() returns NULL assets other than pages CSI-546


  • 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.


  • 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.


  • 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.


  • 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


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


  • 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