Escaping Special Characters in Alfresco CMIS vs. FTS: Understanding the _x002d_ Mystery

As we transition to the new Hyland Community, some post links may be temporarily disrupted as we finalize redirects. We apologize for the inconvenience and are working to resolve this as quickly as possible. Details.

angelborroy

When working with Alfresco, developers often query content using either CMIS (Content Management Interoperability Services) or FTS (Full Text Search). But there's a small gotcha that often trips people up: special characters like hyphens (`-`) behave differently depending on the query language.

If you've ever seen something like _x002d_ in a query and wondered what it means (or why your CMIS query fails when FTS works perfectly) this post is for you.

TL;DR

• CMIS requires escaping special characters (e.g., - becomes _x002d_)
• FTS does not require escaping, so - works as-is
• If your query breaks in CMIS but works in FTS, check your identifiers for special characters

Background: Custom Content Model Example

Let’s say you’ve created a custom aspect called test:test-1. Here’s a sample content model snippet

<aspect name="test:test-1">
  <properties>
    <property name="test:flag">
      <type>d:boolean</type>
    </property>
  </properties>
</aspect>

This aspect might be used in your repository to tag documents with a boolean test:flag

Querying with Alfresco FTS

FTS is flexible with special characters. You can run a query like this with no issues

ASPECT:"test:test-1"

Or combine it with other conditions

ASPECT:"test:test-1" AND test:flag:true

It Just Works™.

Querying with CMIS: Escaping Required

However, try something similar with CMIS and you'll get errors if you don’t escape the hyphen:

❌ Invalid CMIS query

SELECT * FROM cmis:document WHERE test:test-1 IS NOT NULL

✅ Correct CMIS query

SELECT * FROM cmis:document WHERE test:test_x002d_1 IS NOT NULL

Likewise, for properties

SELECT * FROM cmis:document WHERE test:flag = true AND test:test_x002d_1 IS NOT NULL

Here, - is escaped as _x002d_, which is the Unicode escape sequence for the hyphen

Final Thoughts

If you’re dynamically generating CMIS queries, make sure to escape special characters in qualified names (QName). This is particularly important for custom types and aspects with hyphens or other reserved characters.

FTS is more forgiving, but if you're using CMIS (especially in integrations or reporting tools), escaping is not optional.

Still confused? Drop a comment or raise an issue!