Integrate External Content into Communities Using CMS Connect JSON
A strong digital identity allows you to be close to your customers across channels. But it’s often a frustrating process when it comes to delivering, managing, and optimizing experiences consistently across every digital touchpoint.
That can sometimes involve having to recreate content, branding or blogs on your various systems. If you have to regularly update that content, it quickly becomes a costly and repetitive manual task to keep your different systems in sync.
This will no longer be the case if you use CMS Connect. CMS Connect allows all of our Community Cloud customers to leverage their existing content and pull it in dynamically into their Lightning Communities. It lets you centralize your content in whatever CMS system you’ve chosen, without having to re-create content when you want to leverage it in your communities. You’ll save hours of time and effort as you manage your digital experiences!
CMS Connect can pull content from Adobe Experience Manager, WordPress, Drupal, Sitecore, SDL, and others that support content structured as JSON or HTML fragments.
This blog focuses on CMS Connect (JSON). For CMS Connect (HTML), see Connect Your Community to Your Content Management System.
You might be wondering when to use CMS Connect JSON and when to go for HTML.
- CMS Connect (HTML) allows you to integrate fragments of your HTML web content (i.e. headers, footers, and banners, etc) to have the same branding experience of your website into your communities.
- CMS Connect (JSON) is best for when you want to bring in content lists (i.e. blogs, articles, product catalogs, files, etc) including authenticated content.
While this post discusses WordPress as an example, it applies to any CMS that supports JSON.
Let’s get started walking through how you set this up in your Lightning Community!
Before using CMS Connect (JSON)
Before diving in, review these prerequisites so everything goes smoothly.
1. Enable CORS
CMS Connect uses Cross-Origin Resource Sharing (CORS) to access external public content on Salesforce side (CORS is not needed if the content you are pulling in is authenticated).
Make sure to add your Community host to the list of trusted hosts in the CORS header in your CMS system, if the JSON endpoint is not accessible to the Salesforce Communities domain.
For more information about CORS, check out this page.
2. Get the JSON URL
Identify the JSON URL for external content. Supported MIME media type is application/json.
For example, here’s how to get an endpoint from WordPress:
| Type | Description | Example |
| WP Rest API | Send a request to /wp-json/wp/v2/posts by appending it to your site. For details, see WP REST API. | If your site is https://myblog.com, JSON URL to get content is https://myblog.com/wp-json/wp/v2/posts |
| WordPress.com | Use this format: https://public-api.wordpress.com/rest/v1.1/sites/$site/posts. For details, see WordPress REST API. | If your site is https://myblog.wordpress.com, JSON URL to get content is https://public-api.wordpress.com/rest/v1.1/sites/myblog.wordpress.com/posts |
And here are some URL examples for different assets in WordPress:
| Type | Description | Example |
| Post | To get content for a blog post, append postId at the end of the URL. | https://public-api.wordpress.com/rest/v1.1/sites/myblog.wordpress.com/posts/$postId |
| Media Files | Media files in a library of a particular WordPress site can be accessed using REST calls. | https://public-api.wordpress.com/rest/v1.1/sites/$site/media/ |
| Embedded Content | Specify the _embed parameter to indicate to the server that response should include all embedded resources in same request. See WordPress _embed parameter. | https://myblog.com/wp-json/wp/v2/posts?_embed |
CMS Connect (JSON) Configuration
Step 1: Create a CMS connection
Before you can start pulling content into Lightning Community Builder, the first thing you need to do is to actually create and configure the CMS connection in Community Workspaces.
- Go to Community Workspaces.
- Click CMS Connect.
- Click New to create a new CMS connection.
- For Name, enter a friendly name for the connection, for example, Capricorn WordPress.
- For CMS Source, enter the source, such as WordPress. Choose Other only if your CMS is not listed.
- For Server URL, enter the path, such as https://public-api.wordpress.com. Only HTTPS is allowed.
- Do not enter a Root Path for JSON; it is needed only for HTML.
- Under JSON, click Add JSON. For information on properties, see this example.
- Save the settings.
What’s a content item, content list, and content type?
CMS Connect JSON supports two kinds of content: content items and content lists. A content item is a single blog that’s displayed as a full post. A content list is a group of items, such as a blog series. Each list item shows a blurb and a link to the full blog. Content Type is used for grouping related content lists and items. For example:
| Content Type | Content List(s) | Content Item |
| Blogs | Featured Blogs Trending Blogs Top Blogs |
Blog Item |
| News | Trending News Political News Sports News |
News Item |
You can add up to five different JSON content types in a connection, each with up to one JSON content item and ten JSON content lists.
Determine server URL and JSON paths
When you configure a CMS connection, you specify the server URL and the JSON path to the content item or list.
Suppose I’m retrieving blogs from a website hosted on WordPress, https://capricornblog.wordpress.com. These are my JSON URLs:
| Name | URL |
| Content List | https://public-api.wordpress.com/rest/v1.1/sites/capricornblog.wordpress.com/posts |
| Content Item | https://public-api.wordpress.com/rest/v1.1/sites/capricornblog.wordpress.com/posts/{component} |
When I set up the CMS connection, I enter these values for Server URL, Content List Path, and Content Item Path:
| Name | Value |
| Server URL | https://public-api.wordpress.com |
| JSON Path for Content List | rest/v1.1/sites/capricornblog.wordpress.com/posts Note: This path is relative to the Server URL |
| JSON Path for Content Item | rest/v1.1/sites/capricornblog.wordpress.com/posts/{component} Note: This path is relative to the Server URL |
Learn how to extract a JSON field path
For using CMS Connect (JSON), you need to define JSON Path for properties such as ID, Title, Author, etc. But what do you enter for the properties?
Previewing the JSON response shows you the JSON expressions to use for paths to the content. To see a preview, enter the combined Server URL and JSON Path in a browser.
Let’s look at some example JSON responses and the expressions you enter:
Here’s another example. When you specify the _embed parameter in a request, the payload includes _embedded content:
The syntax follows the JSON Pointer specification. For more examples, see CMS Connect (JSON) Expressions.
Step 2: Configure in the Community Builder
After you configure the CMS connection, switch to the Community Builder.
- Drag a CMS Connect (JSON) component to the page.
- Select your CMS Source.
- For JSON Content, select the content item or content list.
- In the component’s property editor, configure the properties.
- In the property editor, prepend each Content List Item Layout attribute path value with an @ sign to indicate it is a JSON expression. (In Community Workspaces, the fields are always a JSON path, so an @ sign is not needed).
- For more information on each of the properties, see CMS Connect (JSON).
Detail page navigation
When you configure a component for a content list, a CMS detail page is automatically created.
When you click Read More, an item’s postId is added to the URL path to retrieve item content. In addition, the detail page enables SEO for that content.
The default page name is {CMSSourceName-ContentTypeName}.
In this example, the CMS Source is Capricorn WordPress and the Content Type is Blog.
The page’s runtime URL is similar, for example, capricorn-wordpress-blog. You can change both the page name and URL from Page Properties.
Congratulations! Your Lightning Community now displays your WordPress blogs.
Summary
Here are the key takeaways:
- If your CMS supports JSON APIs, you can easily reuse content from your communities using CMS Connect (JSON).
- Start by creating a CMS connection and identifying the appropriate JSON endpoint for retrieving content.
- Add the CMS Connect (JSON) component to your community pages and configure its properties.
- When you preview or publish your community page, you see the CMS content.
Additional tips
What if you went through the steps and content doesn’t display?
- Check CORS. Add the Community host to the list of trusted hosts in the CORS header in your CMS.
- The Server URL and JSON Path should be a valid URL that returns a JSON response. For JSON, don’t enter a Root Path. Check that the media type of JSON Response is application/json.
- In the Community Builder, verify the fields in the property editor. For JSON expressions, prepend @, JSON properties are case-sensitive, and should match your CMS payload.
- If a detail page doesn’t appear or navigation doesn’t work, check your connection settings.
- Verify that there’s a content item and content list under the same content type name.
- Verify the ID and Title Path of the content item. For the connection, don’t prepend @ because JSON expressions are expected.
Resources
- Video: How to Reuse CMS Content in your community with CMS Connect JSON
- Webinar: CMS Connect
- Configure Search for CMS Connect JSON Content: Set Up Federated Search in Communities
- Trailhead Module: Community Cloud Basics
You can also register for our new Community Cloud webinar on June 14th, featuring Summer’18 highlights.
About the author
Shipra Shreyasi (@sshreyasi) is an engineer in the Community Cloud team who has been working on building a first-class product and CMS Connect implementation.
