CMS Connect (JSON) Expressions

Reusing your content is a great way to save time and effort. By defining JSON expressions for a CMS Connect (JSON) component, you can map existing content into your site pages.

When you place a component on your site page, you specify its properties using JSON expressions. For example, if you’re mapping in a blog article, you can define expressions to retrieve the blog’s ID, title, author, and content from your CMS.

Let’s look at an example using this JSON structure as the content source. The example JSON response body is from a Drupal CMS.

To set up a CMS connection, create a content item (for example, a blog) or a content list (a blog series). When you add the component to your page, you enter JSON expressions to define its properties.

For example, to retrieve the title, the expression @data/attributes/title retrieves DIY Dryer Vent Cleaning from the example JSON resource. The @ symbol indicates that the text represents a JSON expression that points to the title element.

For CMS JSON connections, the expression syntax follows the JSON Pointer specification in RFC 6901. For the example content source, the parent node @data is the top-level pointer to the source content. To access a nested element, specify the path. For example, the expression @data/attributes/body/value points to the blog content.

When accessing values in an array, the starting index value is 0. Here’s an example of JSON source containing a simple array.

Using this source, the expression on the left yields the output on the right.

You can build more complex expressions using the where, lookup, and concat functions. Use the where function to filter array elements. The function compares two values using an operator: 'eq' (equals), 'ne' (not equals), 'lt' (less than), 'gt' (greater than), 'le' (less than or equals), or 'ge' (greater than or equals).

In the first example, the where expression filters the array to find where the value of key is equal to 2. The second example uses two where functions, and both conditions must be met to find the array element of interest.

The lookup function is useful when searching a JSON document. It takes at least 3 parameters.

• Starting node
• Key to examine inside the starting node
• String or numeric value to match the key against

For example, you can search the JSON source for instances where an author ID or a key matches a certain value.

The concat function concatenates the strings and parameters that you give it. The expression @concat('DIY Focus', ': ', 'about your ' , /array/1/dictionary/d) outputs "DIY Focus: about your Dryer". If your CMS stores the author name in an array with first and last name elements, to output the author’s full name, use an expression such as @concat(author/first_name,' ',author/last_name).

Keep these points in mind when you compose JSON expressions.

• Enclose strings in single quotes. For example, @'hello' is how you include the string hello in an expression. To include an @ character in a string, enclose it in single quotes. For example, 'myname@gmail.com'.
• Use true or false to indicate a Boolean value. The value true is a Boolean, but 'true' is a string.
• Specify a sibling or parent element relative to the current context using a period (.) for a sibling and two periods (..) for a parent. For example, to search by title, specify @data/attributes/title/../id to retrieve the corresponding ID for a title.
• Use the backslash character (\) as an escape character. For example, @/author/name looks for name under an author element, but @/author\/name looks for author/name as a key.

Mistakes happen sometimes. Here’s a couple of possible error messages when your JSON expressions aren’t right.

• Entering an invalid JSON path in the property editor of Experience Builder. For example, if you enter a JSON expression for author as @author/invalid instead of @author/name, you see an error message like this one.

  

• Entering an expression that returns more than one value when only one value is expected. For example, if you enter a JSON expression for author as @author instead of @author/name, you see this error message.

  

• Providing an invalid URL path when you create a CMS connection for a content list or connection details. Depending on the issue, you see HTTP errors, such as HTTP 0 or HTTP 404 errors, or an error like this one. Verify the configuration settings for your CMS connection.

  

• CMS Connect Examples
• Set Up a Connection for Your JSON CMS
• Add CMS Connect (JSON) Components to Your Site Pages
• Metadata API Developer Guide: CMSConnectSource