New Features

• Content Mentions GA
• Prefix search for auto-suggest
• Message Editor v2 (Early Access)
• Better visual display for code samples
• In-line image editing
• Streamlined editing pane
• Toolbar button optimization and consistency
• Improved Emoji support
• GDPR “soft-delete” support
• Change a user's login using an HTTP endpoint (SSO only)
• API changes

Content mentions GA

In the 18.12 Release, we announced the Early Access release of Content Mentions. We are happy to announce that Content Mentions is now GA and no longer requires a Support ticket to enable.

Note: Content mentions is supported only on Responsive communities.

To get started with Content Mentions:

• Set the Mentions feature to version 2 in Studio > Features. (You no longer need a Support ticket to enable User or Content mentions.)
• Grant users the Mention content in posts permission in Community Admin.
• Turn on Content Mentions under Admin > Features > @Mentions.

As part of the GA release, Content Mentions now supports email notifications when a user's message is mentioned in a post and content keyword search. We’ve added a new @Mention Content Notification email template in Studio.

To view and edit the @Mention Content Notification template:

1. Sign in to Community and go to Studio.
2. Go to Text Editor > Email Text.
3. Select @Mention Content Notification from the email template drop-down list.
4. Click View.
5. Make changes to the email text as needed and click Save.

Content Mentions default notifications are configured in Community Admin. Members can configure their notification preferences, too:

• For admins: Users > Notification Defaults > Notifications > Posts my content is @mentioned in.
• For members: My Settings > Subscriptions & Notifications > Notification Settings > Posts my content is @mentioned in.

Finally, the GA release of Content Mentions also takes advantage of the prefix search functionality, so as you begin typing your content mention, you see matching results as you type:

Learn more about Content Mentions.

Prefix search for auto-suggest

We have improved the auto-suggest capabilities for community search so that you start seeing matching results as you type, instead of waiting for the whole word to be typed.

For example, when searching for topics/answers on “gdpr”, you used to need to type in the complete word in the Search field to see auto-suggest results:

Now, Search auto-suggest serves up answers as you type as soon as it finds matching results:

Message Editor v2 (Early Access)

We’ve made several improvements to our message editor (which currently uses TinyMCE version 4.7.13). Improvements include:

• Better visual display for code samples
• In-line image editing
• Streamlined editing pane
• Toolbar button optimization and consistency
• Improved Emoji support

Requirements: These message editor enhancements require Responsive, Media v4 or higher, and Editor v2. Learn more about Feature Versions.

Message Editor v2 is currently available as Early Access. Open a Support ticket to request access. (Before having Editor v2 enabled, we recommend reviewing your current implementation to assess the impact of any customizations you’ve made.)

Enable Editor v2 (Early Access)

Before upgrading to Editor v2, we recommend reviewing the all the new features and user interface changes that are included in Editor v2. You cannot pick and choose specific features; if you update to v2, you get all of these features and improvements.

Similarly, we recommend reviewing your current implementation to assess the impact of any customizations you’ve made.

Note: Message Editor v2 is currently available as Early Access. Open a Support ticket to request access.

To enable the new version of the message editor:

1. Sign in to Community.
2. Go to Studio > Features.
3. Set the Editor version number to 2.
   
   
4. Click Save.

Better visual display for code samples

For Editor v2, the updated editor provides color coding for code samples in your posts to improve overall readability.

To enter code samples when composing a message:

1. Click the Insert Code icon.
   
   
2. Choose the coding language from the list.
   
   
3. Start typing (or copy/paste) your code sample.
   
   

Here’s an example of a more robust code sample:

Note: If you have applied custom CSS on the li-code tag, that styling will override these display improvements. To leverage the out-of-the-box styling, simply remove your custom CSS.

In-line image editing

In the previous version of the message editor, you could only perform the light, image editing tasks on images when you uploaded them to the community.

In Editor v2, when a user clicks on an image while editing a post, the image is highlighted and provides these editing options:

• Alignment (left, center, right)
• Sizes (small, medium, large)
• Edit (opens modal window where you can add caption, resize and reposition)

Streamlined editing pane

To improve the overall usability of the message editor, we have replaced the multiple tabs (Rich Text, HTML, and Preview) with a single, editing pane in Editor v2.

Note: The improved editing pane displays the content very close to how it will look like when published, mostly negating the need for the Preview tab. However, we plan to provide a new “preview mode” option in a future release. The improved editing pane will continue to pick up any custom styling in your SCSS that applies to message styling.

To view and edit the HTML source for the page (which is sometimes needed to clean up HTML formatting when copy/pasting content from other sources), you can click the Source Code icon in the toolbar:

A window opens where you can view/edit the HTML source code directly.

Removed Admin settings

Since the tabbed view of the message editor has been removed, the two admin settings associated with the configuration settings of these tabs have been removed. When you use enable Editor v2, the Discussion Styles > Posts & Topics > Settings tab no longer includes these setting options:

• Default editor to use for posts
• Display Rich Text, HTML, and Preview tabs

Toolbar button optimization and consistency

For Editor v2, we have done a full audit of the editing toolbars and have optimized them for specific discussion styles and size formats. Additionally, we have standardized the drop-down menu options across all the toolbars.

Editor v2 provides these toolbars:

• Full toolbar (for Blogs and TKB)
• Simple toolbar (for all other content types)
• Responsive mobile

Full toolbar (for Blogs and TKB)

Blog and TKB content require the most robust editing controls. As such, the editing toolbar includes the most options:

• Top row buttons
• Format
• Align left
• Align Center
• Align Right
• Justify
• Bullet list
• Numbered list
• Decrease indent
• Increase indent
• Spoiler tag
• Source code
• Table of Contents
• Find Content (TKB only)
• Bottom row buttons
• Bold
• Italic
• Underline
• Strikethrough
• Text color
• Font sizes
• Font family
• Clear formatting
• Insert code
• Insert link
• Insert emoji
• Insert image
• Insert video
• Table

Simple toolbar (for all other content types)

All other content types (Questions, Ideas, Contests, comments, replies) don’t usually require advanced editing options. As such, a simpler toolbar is used:

Buttons

• Bold
• Italic
• Bullet list
• Numbered list
• Clear formatting
• Insert link
• Insert emoji
• Insert image
• Insert video
• Expand toolbar

Note: Clicking the ellipsis (...) button opens the Full toolbar, described above.

Responsive mobile

On mobile devices, where screen real estate is at a premium, the toolbar includes only the most common actions:

Buttons

• Undo
• Bold
• Italic
• Bullet list
• Styles
• Insert link
• Insert image
• Insert video

Consistent button drop-down menus

Across all the toolbars (Full, Simple, Responsive), we have made standardized the options in these drop-down menus:

• Format
• Bullet list
• Numbered list
• Text color
• Font sizes
• Font family
• Table

Improved Emoji support

For Editor v2, we’ve improved our emoji support to provide community admins with a lot more flexibility over which emojis to make available in the message editor as well as the ability to create a custom set of emojis. For example, you might want to create emojis specific to your brand or products.

To configure emoji support for your community:

1. Sign in to community as an Admin.
2. Go to Admin > Display > Emojis.
   
   
3. By default, emojis are enabled on your community.
   Click Turn off emojis everywhere to turn off Emoji support.
4. Click Turn off emojis within preformatted text to disable text from being converted to emojis in preformatted (code) text.
5. Select or clear specific emoji categories, depending on which ones you want to include in the message editor’s Emoji drop-down menu.
   
   
6. For each Emoji category, you can include or filter out specific emojis. Click the View All link next to each category and click specific emojis to turn them on or off.
   
   
7. Click Save.

Note: At this time, Custom emojis (ones you create specifically for your community site) are either all available or none are available. You cannot selectively hide emojis in your Custom emoji category. To remove an emoji from the Custom group, you must delete the emoji from Studio.

Create a set of custom emojis

Some brands have a custom set of emojis that they want to make available in the message editor. You create and manage this set of custom emojis in the Studio asset library. You can have only one set of “custom” emojis, and they all are stored in the “Custom” emoji category.

To create custom emojis:

1. Sign in to community and go to Studio.
2. Go to Community Style > Asset Library > Emojis.
   
   
3. At the bottom of the custom emoji list, enter the Emoji Name for your new emoji.
4. In the Upload an Image field, click Choose File and select the image to use for this emoji.
   Note: Custom emoji icons cannot be larger than 128x128 pixels and must be smaller than 64KB. Emoji icons can be in .bmp, .jpg, jpeg, .gif, .png, and .svg format.
5. Click Add Emoji.

To delete an emoji from the Custom emoji list, click the Delete (trashcan) icon in the row of that emoji.

Note: At this time, you cannot edit the name or image for an existing custom emoji; you must delete the emoji and recreate it.

Using emojis in the message editor

To add an emoji to your post:

1. While writing your article/post, click the Emoji icon in the message editor toolbar:
   
   The Emoji chooser opens:
   
   
2. Scroll through the list to find the emoji you want to add. Or, click one of the emoji categories along the top of the chooser. (The asterisk category (*) is your brand’s custom emoji set; this category appears only if you have created and enabled a set of custom emojis.)
   Tip: If you know the name of the emoji you want to use, you can type its name to search for it quicker:
   
   
3. (Optional) You can select the skin tone to use for emojis that support different skin tone colors.
   
   
4. Click the emoji image.

The emoji is added to the body of your message.

Tip: Additionally, you can type the emoji name (starting with a colon) to directly in the message editor pane. Doing so initiates an emoji search and preview of emojis matching that name:

If an emoji is later removed from the Custom emoji list, hidden, or if emojis are turned off completely for the community, the emojis alternative text (for example, “:smiley:”) is used in place of the emoji image.

Mac vs. Windows emoji display: The emoji screenshots used in these instructions are for Mac. On Windows machines, the emojis will look a little different. For example:

GDPR “soft-delete” support

As part of our support for GDPR, we have provided for a soft-delete period for all user deletes. During this period of time, it is possible to undo an account deletion and restore the deleted user account. To request an account restore, open a Support ticket.

This soft-delete window provides a built-in safety feature to handle any accidental or malicious deletes. After the soft-delete window (default is set to 10 days) has passed, all user account deletes are permanent and irrecoverable.

During the soft-delete period, the user name is reserved and cannot be used when creating a new account. After the soft-delete period elapses, the deleted username will be available again for new users.

Note: This 10-day period is subsumed in 30-day SLA for user deletes.

Note: When querying for the number of deleted accounts via the API, the response does not include any accounts in a soft-delete state, only accounts that have been hard deleted.  

The soft-delete period set to 10 days by default, but is configurable. The recommended maximum value is 10 days so as to not risk the GDPR-mandated 30-day SLA for account deletions. To request a change to the default value of 10 days, open a Support ticket.

No action is required on your part to activate this feature and use the default configuration.

Change a user's login using an HTTP endpoint (SSO only)

A subset of customers using Single-Sign-on (SSO) and who are also the Identity Provider (IDP) require a way to change a user's login via an HTTP endpoint. This enables these customers to sync login name changes on their side with logins in Community. 

To provide this support, we have added a new configuration setting, disabled by default and enabled by Support. 

When the setting is enabled an SSO-enabled user's login can only be changed via the Community REST API. (It cannot be changed through UI by the user or by an administrator.)

To enable this new configuration, open a Support ticket and request enablement for API-Only Allowed Login.

To update a login, make a PUT call to the users collection (Community API v2) or call the user/login/set endpoint (Community API v1).

API Changes

19.1 brings updates to

• Community API v2 Message, Conversation, Subscription, and User objects
• Community API v1 group roles endpoint
• FreeMarker

Community API v2

• Message object updates
• Conversation object updates
• Subscription object updates
• User object updates
• Initiate the Reset Password flow

Message object updates

New fields

We've added new fields to the Message object.

• board_relative_id - the board-relative message ID. This could be used in custom components that incorporate inline anchors to jump to a specific message, for example, or to create a custom CSS class that differs by the message ID within
• context_id - Metadata on a message to identify the message with an external identifier of your choosing. You may create or edit a message with context_id and then query for messages by context_id using context_id in the WHERE clause of a LiQL query. You may add a single context_id per message.
• context_url - Metadata on a message representing a URL to associate with the message. This is an external identifier of your choosing. You may create or edit a message with context_url and then query for messages by context_url using context_url as a constraint in the WHERE clause of a LiQL query. You may add a single context_url per message.
• is_escalated - whether the message has been escalated
• moderation_style - The moderation style based on the Community Admin setting for the given board. Supported values: off, pre, post

Order queries to the messages collection by the more recent of two timestamps

You can now order queries to the message collection in the ORDER BY clause by the more recent of these timestamps:

• the post date of the latest reply in a given thread (equivalent to the conversation.last_post_time field)
• the last publish date (last non-draft message revision) of the thread topic

Note: conversation.last_posting_activity_time is a new field on the Conversation subobject.

The value of conversation.last_posting_activity_time will often be the same as the last_post_time of a conversation, but if the last publish date of the topic message is more recent, then sorting by conversation.last_posting_activity_time will show that date instead.

Example

SELECT subject, id FROM messages WHERE conversation.last_posting_activity_time > 2013-10-07T10:04:30-08:00 AND conversation.last_posting_activity_time < 2013-11-07T10:04:30-08:00 AND depth=0 ORDER BY conversation.last_posting_activity_time DESC

Conversation object updates

We have added the last_posting_activity_time field to the Conversation object. This field will be the more recent of either the conversation.last_post_time or the last publish date (last non-draft message revision) of the thread topic. This field must be called explicitly in the SELECT statement in order to be returned. See the previous section for more details about how to use this new field.

Subscription object updates

You can now subscribe a user to labels and products with Community API v2. See Creating user subscriptions with Community API v2 for examples.

User object updates

• New LIKE clause constraint for the login field

New LIKE constraint on login field

We've added a new LIKE operator in the WHERE clause on the login field of the API v2 users collection. The LIKE operator works similarly to SQL LIKE clauses: you may add either 1 or 2 wildcard characters (the % sign) and you must have at least 3 non-wildcard characters in your LIKE string. Examples: doug%, %suz%, 'john%.

SELECT id, login FROM users WHERE login LIKE 'doug%'
SELECT id, login FROM users WHERE login LIKE '%suz%'
SELECT id, login FROM users WHERE login LIKE '%john'

The first example (LIKE 'doug%') would return user logins such as doug, dougP, douglasAdams, doughnutsAreDelicious, and so on.

You may use the LIKE operator only with the login field of the users collection. You can use LIKE alone or with other constraints in the WHERE clause.

• You may use Unicode characters in a LIKE clause.
• You may include a % sign as a non-wildcard by escaping it. Escape a % by including two percent signs next to each other (%%) in your search string.

Note: If you use LIKE in a query that also uses the following.id or followers.id constraints in the WHERE clause, then your wildcard characters must be before and after the rest of the LIKE string.

These queries are valid when using followers.id or following.id:

SELECT id, login FROM users WHERE following.id = '2' AND login LIKE 'doug%'
SELECT id, login FROM users WHERE followers.id = '4' AND login LIKE '%suz%'
SELECT id, login FROM users WHERE following.id = '5' AND login LIKE 'john%'

These queries are not valid:

(% is used in the middle of the LIKE string)
SELECT id, login FROM users WHERE following.id = '2' AND login LIKE 'do%g%'

(LIKE string includes only two non-wildcard characters. Three minimum are required.)
SELECT id, login FROM users WHERE followers.id = '4' AND login LIKE '%su%'

Initiate the Reset Password flow

We've added a new Community API v2 endpoint /auth/resetPassword. This new endpoint is intended for use in native Android and iOS mobile Community integrations when an anonymous user wants to reset their password. (Community web app developers can simply redirect a user to the Forgot Password Page to start the reset password flow.)

A POST call to the endpoint initiates the rest password flow for the email sent in the request body. You make this call as an anonymous user passing your app's client ID in the header for security verification. The endpoint verifies whether the user exists and is registered with the current email provided in the request body.

Note: To use this endpoint, you must file a ticket with Lithium Support and request Reset Password API Enablement.

Header Parameter

Content-Type: (Required) application/json

client-id: (Required) Obtain your client-id in Community Admin > System > API Apps. If you have not yet registered your Community web app in Community Admin, click Create Web App, provide a display name and authorization redirect URL, and click it verifies whether the user exists and is registered with the current email provided in the request body. Your client-id appears in the Client ID column.

Request Body

email: (Required) The email address associated with the user wanting to initiate a password reset

cURL Example

curl -X POST \

https😕/[COMMUNITY DOMAIN]/api/2.0/boards \
 -H 'content-type: application/json' \
 -H 'client-id: [CLIENT ID]' \

 -d '
       { "email" : "email_address@email.com" }
    '

Response codes

A POST call returns one of the following codes:

200 - (Success) Returned if the required configuration setting (enabled by Support) is enabled and the payload includes an email item (regardless for the email validity)
400 - (Client Error) Returned if the payload is not present

403 - (Client Error) Returned if no client-id or an improper client-id is sent in the header
503 - (Service Unavailable) Returned if the required configuration setting is disabled

Community API v1

We have added an optional String query parameter to the /groups/id/[id] /group_roles Community API v1 endpoint. By default, this call returns a list of roles defined for the specified group. When the new roles.include_ancestors query parameter is true, the call also returns group roles inherited from ancestor nodes.

Example resource URL

/restapi/vc/groups/id/group_id/group_roles?roles.include_ancestors=true

FreeMarker updates

We're pretty excited about these updates. We've got a new convenience method to make a LiQL call with a single argument, and you can now make POST, PUT, and DELETE calls to Community API v2 with the rest and restadmin context objects.

Make POST, PUT, and DELETE HTTP actions to Community API v2 via FreeMarker

We have updated the rest and restadmin FreeMarker context objects to enable you to make POST, PUT, and DELETE calls to Community API v2 in addition to GET calls. POST, PUT, and DELETE actions made with FreeMarker take a new set of parameters, described later in this section. You may continue to make GET calls with the following syntax  (rest("rest_version","/search?q=" + "liql_query"?url)) or you can use the new liql and liqladmin context objects instead.

Example POST (create)

<#-- Build the requestBody parameter and assign it to a variable-->

<#assign messagePostBody = {
 "type": "message",
 "subject": "How do I post a REST API message?"
} />

<#-- Make your REST call with the rest or restadmin object -->
<#assign resp = rest("2.0", "/messages", "POST", messagePostBody) />

...

Example PUT (edit)

<#-- Build the requestBody parameter and assign it to a variable-->

<#assign messagePostBody = {
 "type": "message",
 "id": "34",
 "subject": "How do I post a REST API message?"
} />

<#-- Make your REST call with the rest or restadmin object -->
<#assign resp = rest("2.0", "/messages/34", "PUT", messagePostBody) />

...

Example DELETE

<#-- Make your REST call with the rest or restadmin object -->
<#assign resp = rest("2.0", "/messages/34", "DELETE") />
...

The rest and restadmin methods now take the following parameters when making POST/PUT/DELETE calls  to Community API v2 with FreeMarker:

• rest("version", "path", "method", "requestBody")
• restadmin("version", "path", "method", "requestBody")

Example use in endpoint posting a message

<#assign subject = http.request.parameters.name.get("subject", "") />
<#if subject?length gt 0>
	<#assign messagePostBody = { 
	  "type": "message", 
	  "subject": subject, 
	  "board": { "type": "board", "id": "Otis" } 
	} />

	<#assign resp = rest("2.0", "/messages", "POST", messagePostBody) />
	${apiv2.toJson(resp)} 
<#else>
 { 
   "status": "error",
   "message": "no subject parameter passed."
 }
</#if>

New liql and liqladmin context objects

We've added new liql and liqladmin context objects. They are convenience methods and alternatives to using the rest and restadmin context objects to make a LiQL call. liql and liqladmin enable you make a LiQL call with a single argument.

Note: Like restadmin, the liqladmin context object makes the call to the Community REST API with administrator permissions on behalf of the current user. Be careful when using liqladmin that you are not inadvertently returning or revealing data to a user who should not be seeing it.

This call to the rest context object:

rest("2.0","/search?q=" + "SELECT id, subject, body FROM messages ORDER BY post_time DESC LIMIT 5"?url)

Can now be made like this with liql or liqladmin:

liql("SELECT id, subject, body FROM messages ORDER BY post_time DESC LIMIT 5")

You do not URL-encode the LiQL query when calling liql and liqladmin. Both ways of making GET calls to the Community API with FreeMarker are supported. You do not need to update existing code

liql call format

liql("liql_query")

Example

<#-- Make your LiQL query call -->
<#assign resp = liql("SELECT id, subject, body FROM messages") />
…
<#-- Do something with the response -->

The liql and liqladmin context objects take the following parameters:

liql("version", "query", "characterSet")
liqladmin("version", "query", "characterSet")

http.response support in endpoints

We now support the following http.response methods in Lithium endpoints. Previously, these call were only allowed in the page initialization script:

• addHeader("header_name","header_value") - add an HTTP response header
• setRedirectUrl("redirect_url") - set a redirect URL. Will use status code 301 until another redirect status code is set with http.response.setStatus.
• setContentType("content_type") - set a different content type for the request
• setStatus("status_code") - This is a new method that lets you set the HTTP status code

Note: setStatus("status_code") is supported in endpoints only. Continue to use  setRedirectStatus(status_code) in the page initialization file (common.init).

You Found It. We Fixed It.