Release Notes

20 MIN READ

14.10 Release Notes

Khoros Alumni (Retired)

11 years ago

In the 14.10 Release, we’re excited to introduce Lithium Community REST API v2. This next-generation Community API is optimized for personalization, content discoverability, and relevancy. It also provides a much smoother integration path with third-party systems. With Community API v2, we are exposing many more resource fields than we made available in API v1. We’ve also made accessing those fields much more intuitive through Lithium Query Language (LiQL), a SQL-like query language.

In our continued effort to create the best mobile community experience possible, Community Mobile v2 now supports the TKB discussion style.

As announced last week, Lithium Social Intelligence now provides new and improved Community Health Index (CHI) reports and the ability to export bulk data from the community via the API.

New features and enhancements

Community API v2 and LiQL
TKB for Community Mobile v2
Ability to export Admin settings
@Mentions support for TKB
Mondrian community skin
Community Health Index (CHI) in Lithium Social Intelligence (beta)
Lithium Community Bulk Data API
API changes
More secure method for setting font sizes in TinyMCE

Community REST API v2 and LiQL

We are very excited to introduce Lithium Community REST API v2. This next-generation Community API is optimized for personalization, content discoverability, and relevancy. It also provides a much smoother integration path with third-party systems (without adding a penalty when upgrading).

This API was completely redesigned to:

Increase extensibility thereby enabling you to extract more value from the platform
Be easier to learn and use
Have fewer and more efficient calls to simplify code complexity
Be extremely flexible for both mobile and desktop development

We are exposing many more resource fields than we made available in API v1. We’ve also given you more control to filter and sort those fields through Lithium Query Language (LiQL), an open-sourced, SQL-like query language. With a LiQL statement you can define search criteria for a vast variety of complex queries. For example:

Return forum posts that have an average rating value of 4 or higher.

SELECT * FROM messages WHERE ratings.avg(value)>=4 AND conversation.style='forum'

Return the subject, ID, and conversation data for forum topics with accepted solutions.

SELECT subject, id, conversation FROM messages WHERE conversation.style= 'forum' AND depth=0 AND conversation.solved='true'

LiQL is more intuitive because you can specify exactly what data you want without having to find and chain multiple calls together. Say you want to return the IDs of the four most recently posted topic messages from a specific category, authored by a specific user. Here’s your LiQL statement:

SELECT id FROM messages WHERE category.name = ‘recipe_board’ AND author.id = '3' AND depth = 0 ORDER BY post_time DESC LIMIT 4

The same call in a custom component using API v1 would look something like this:

rest("/users/id/3/topics/in/boards/id/recipe_board/recent?page_size=4")

You would have to use the users/id/[user_id] call on the Community resource, and then chain a method from the User resource to get the topics from a specific board.

With LiQL, you can query the community with a single STATEMENT from any node level. No more determining what calls are available for what resource type. No need for secondary code, no need to make a second call to sort the messages by date/time.

Where Can I Learn More?

Check out our new Community API v2 knowledge base on the Developer Network. Begin with Getting Started and Using LiQL, then learn more about the response, error responses, application error codes, and OAuth2.

Note: While Community API v2 offers many new features and functionality over API v1, at this time v2 does not fully replace v1 for all customers. We recommend that you used API v1 and v2 in parallel until v2 has the features needed to replace v1. In the meantime, refer to this article to decide when to use Community API v1 or v2.

We’ve also added a new API Browser tab in Studio. In this tab, you can make LiQL calls from a GUI interface, which is great for experimenting and getting to know API v2. Calls made in the API Browser are made using the permissions of the signed in user.

Finally, each new resource, such as the Message resource, has an individual knowledge base article with property descriptions, a list of properties available for use in LiQL constraints, and example queries.

A Few More Things To Know

API v2 is currently accessible to all signed in and anonymous users. This is a change from API v1 where the “Make REST API calls with read access” and “Make REST API calls with modify access” user permissions controlled access. However, the actions a user can take through the API are dictated by his or her permissions. For example, anonymous users can only read public data; they cannot post messages or access private boards or categories. On private communities where anonymous access is disabled, anonymous users cannot access the API at all.
API v2 calls made over HTTP require authentication via OAuth 2.0. OAuth requires each client application to be registered and use an application key and secret. Contact Support to register your client applications and generate your key and secret. We are working to make this self-service in a future release.
Each API v2 call is counted as a Billable Application Call (BAC) for billing purposes. If you are unsure what your monthly BAC allowance is, please contact your Account Executive.

As always, we welcome feedback and contributions. As you get started with Community REST API v2, we encourage you to share samples and let the rest of the developer community see the innovative features and tools you create. And we’d love to hear your suggestions for future tech blog posts. Let us know if you’re interested in contributing one.

How to get it?

All communities upgraded to 14.10 get Community API v2 automatically.

TKB for Community Mobile v2

As first announced in the Community Mobile v2 Release Notes, Lithium has re-invented its mobile community experience from the ground up. Optimized for new-user engagement, Community Mobile v2 makes it easy for users to participate on the community wherever they are.

Note: If you are interested in upgrading to Community Mobile v2, contact your account manager. As described in the Community Mobile v2 Release Notes, this functionality is being rolled out on a controlled schedule.

With the 14.10 release, Community Mobile v2 now supports the TKB discussion style.

TKB for Community Mobile v2 has been optimized for content consumption to enable new users to find the information they want and join the discussion. As such, in Community Mobile v2 TKB:

Users can’t author new TKB articles
Users must be registered to comment

Important: At this time, customizations must be done in cooperation with Lithium Professional Services. To discuss customization options and create a statement of work, contact your Account Representative.

How to get it?

All communities upgraded to 14.10 that are using Community Mobile v2 get TKB support automatically.

Ability to export Admin settings

We’ve added the ability for community managers to export their Community Admin settings to a single XML file, which you can search more easily.

Note: The exported XML file includes only community-level settings, not category- or board-specific settings.

To export Community Admin settings to an XML file:

Go to Community Admin > System > Maintenance.
Click the Admin Settings tab.
Click Export.

How to get it?

All communities upgraded to 14.10 get this feature automatically.

@Mentions support for TKB

With the 14.10 release, users can now @Mention other users in TKB comments, and those users are notified (if notifications are enabled) when someone mentions them in the comments of a TKB article.

To learn more about the @Mentions feature, check out About Mentions. To learn more about setting up @Mentions notification defaults, read Set Mention email notification defaults for users.

Mondrian community skin

With the 14.10 release, we’ve introduced a new community skin, called Mondrian. Inspired by the artist Piet Mondrian, the new Mondrian skin focuses on simplicity and beauty.

Mondrian is now the default skin used for new communities. You can use Mondrian out-of-the-box, create a copy and customize it for your brand, or use a different skin altogether.

Note: If you have already launched your community, you just can’t “switchover” to Mondrian without re-doing your site customizations and going through a community re-launch.

To use the Mondrian skin on your community:

Go to Community Admin > Display.
Click Skins.
Scroll down the list and select Mondrian.
Click Save.

Community Health Index (CHI) in Lithium Social Intelligence (beta)

In our continued effort to provide you with the best reporting tools and analytics for your community, we have transitioned the Community Health Index (CHI) score from the Customer Intelligence Center (CIC) to Lithium Social Intelligence (LSI).

Note: With this migration, we have permanently discontinued the Customer Intelligence Center (CIC).

To view your community’s CHI scores in LSI:

Sign in to your community as an Admin.
Click Lithium Social Intelligence.
Click CHI.

The graph shows your overall CHI Trend over all six health metrics (members, content, traffic, interaction, liveliness, and responsiveness) for the selected date range.

Note: This graph includes both your current CHI score, based on the improved calculation approach and the old CHI score, based on how Lithium used to calculate CHI. Click CHI or Old CHI in the bottom-left corner to show or hide each graph.

Why is my new CHI score different from my old CHI score?

In addition to migrating CHI to LSI, we have modified the calculation of the scores by implementing the following calculation changes:

Eliminated bot traffic from the calculations.
Made the new CHI score more sensitive to more recent actions/events instead of 50 weeks of activity.
The old CHI was computed on a weekly basis starting on Sunday; the new CHI scores are computed on Monday.
Included private boards in our calculations.
Note: Active, internal private boards now have a positive impact on your score; inactive (archived) boards might have a slightly negative impact, but overall, it’s a net gain.

As a result of these changes, you will see more peaks and valleys in your CHI values, but also a better reflection of your community’s current health.

Will I still get my Community Health Reports (CHR)?

If you were receiving CHR emails from insights@lithium.com, you will no longer receive these emails. Instead, you can schedule your own CHI reports to be emailed to you via LSI.

How long after launching a new community can I start using CHI as a proxy for my community’s health?

On old CHI, we recommended waiting 3 months before using CHI to measure your community’s health. However, since new CHI is more responsive, you can start using the CHI score after one week. Be aware that over longer data ranges, most communities still converge around a consistent score, even if there is volatility from week to week.

How to get it?

All communities using LSI get the new CHI reports automatically.

Lithium Community Bulk Data API

The Community Bulk Data API provides greater reporting flexibility and expands the analytics capabilities of Lithium Social Intelligence (LSI). It gives brands the option to build custom reports using Lithium community data with their own business intelligence tools. The Lithium Community Bulk Data API provides a daily extract of event logs for a specified community in JSON or as a flat CSV file. Lithium event logs capture client-side request information as well as all associated information related to the request.

These events are aggregated into the Page View, Post, or Kudos counts you see in the Lithium Social Intelligence (LSI) application. The Bulk Data API excludes bot and crawler traffic, which mimics the event/traffic data in LSI. You can use this API to store the community event logs for specific days in your own data store and then use your own report builder tool to build custom metrics, KPIs, and reports that you can schedule and run on a regular and automated basis.

Note: You must have license access for the instructions below to work. If you have questions about your licensing access, contact your Account Representative.

Here’s a sample Bulk Data API call:

curl “https://api.lithium.com/lsi-data/v1/data/export/community/<community_id>?fromDate=YYYYMMDDhhmm&toDate=YYYYMMDDhhmm” –H “client-id: <client-id>” –u “<token>:”

where:

community_id is the unique community ID (contact Lithium support)
client-id is the client application ID (contact Lithium support)
token is the authentication token, which you can get from LSI

For example:

curl “https://api.lithium.com/lsi-data/v1/data/export/community/<community_id>?fromDate=YYYYMMDDhhmm&toDate=YYYYMMDDhhmm” –H “client-id: <client-id>” –u “<token>:”

To get your token and client-id:

Confirm with your Lithium account team that your license entitles you to Bulk Data API.
Get your Community Admin to grant you privilege for LSI Admin Access.

Sign in to Lithium Social Intelligence.
Click your user name.
Copy down your token in the Profile window.

Contact Support to get community-id and client-id.

For example, this request:

curl “https://api.lithium.com/lsi-data/v1/data/export/community/testcommunity.prod?fromDate=201409131205&toDate=201409141205” –H “client-id: safkdndkebbdkkkc” –u “eicncladjiickld:”

returns this information:

“action.key”, "visitor.id", "community_app", "event.time.ms", “request.geo.country", "request.url.host", "request.headers.user_agent", "node.ancestor_path", "request.device", "user.community.rank.name", "action.is_solution_view", "conversation.uid", "board.uid", "request.headers.referrer.url", "user.uid", "user.community.role.name", "visit.id", "action.duration", "action.span.seconds", "action.weight", "target.user.uid", "target.user.community.rank.name", "target.user.community.role.name", "message.uid", "message.is_topic", "message.type"

Exporting this information to Excel produces a file like this:

If you prefer to get your data in JSON format, add the following header to your request: Accept: application/json

Known Limitations

A community can send only one API request at a time. The data source is the same data store that LSI production uses, so we have added some constraints to minimize concurrent requests that could slow down LSI response times.
Currently, each API request can request only up to 24 hours of data.

For definitions and examples of each column value, refer to Using the Lithium bulk data API.

How to get it?

To use the new Bulk Data API, you must have license access. If you have questions about your licensing access, contact your Account Representative.

API changes

Product Search APIs on the Community resource

We enhanced the Ratings and Reviews feature and Community search functionality by creating APIs to search for products. The APIs function similarly to existing APIs to search for messages, users, and images using the Community/search endpoints.

With the new APIs you can:

Search for products
Search for products within one or more product categories
Sort search results by the average 5-star product rating in either ascending or descending order
Filter searches using the same search query parameters you use with message, user, and image searches

Search all products

http://your_community.lithium.com/restapi/vc/search/products

<response status="success">
   <product_viewer type="product_viewer">
      <view_items>
         <view_item type="product" href="/products/id/Pizza">
            <ratings_average type="float">4.5</ratings_averageprod>
            <title type="string">Pizza</title>
            <id type="string">Pizza</id>
         </view_item>
         <view_item type="product" href="/products/id/regress147">
            <ratings_average type="float">4.0</ratings_average>
            <title type="string">147 waterbottle</title>
            <id type="string">regress147</id>
         </view_item>
            <view_item type="product" href="/products/id/FairyLantern">
            <ratings_average type="float">5.0</ratings_average>
            <title type="string">Fairy Lantern</title>
            <id type="string">FairyLantern</id>
         </view_item>
      </view_items>
</product_viewer>
</response>

Examples

Search products within a product category

http://your_community.lithium.com/restapi/vc/search/products?q=product.category:prodCategory1

Search products within multiple products categories

http://your_community.lithium.com/restapi/vc/search/products?q=product.category:prodCategory1%20OR%20product.category:productCategory2&sort_by=ratingsAverage:review_ratings

Sort search results in ascending order

http://your_community.lithium.com/restapi/vc/search/products?sort_by=ratingsAverage:review_ratings

Sort search results in descending order

http://your_community.lithium.com/restapi/vc/search/products?sort_by=-ratingsAverage:review_ratings

Search query parameters

The search/products APIs use the same optional search parameters that you are familiar with. If you are new to the search APIs, this article provides an introduction.

Parameter	Type	Description
f (optional)	string	The field to search on. When you use the f parameter, you must also pass the q parameter to define the text string to search for. If you do not supply the q parameter, no filtering occurs. Text passed with the f parameter is case sensitive. You can search on the following fields of the Product resource: id title description Average.review_ratings category Example: Return products with Jacket in the product title http://your_community.lithium.com/restapi/vc/search/products?q=product.title:Jacket
q (optional, but required when using the f parameter)	string	A text string to search for. Text passed with this parameter is case insensitive. You can optionally specify a field to filter by using the format q=<field_name:text_string>, such as “product.id:iPhone”. For example: q=product.description:waterproof returns products with a product description that includes the word waterproof. Use “+” to search for multiple text strings in cases where all of the strings must exist within the same field. For example: q=speaker+wireless returns products where both “speaker” and “wireless” appear in a field value. Use OR (case sensitive and encoded with %20 before and after) to search for multiple text strings when you want to search across multiple fields of a product. For example: q=iPhone%20OR%20Android returns products where either iPhone or Android appear in a field value. Example: http://your_community.lithium.com/restapi/vc/search/products?q=product.title:Lantern
phrase (optional)	string	A phrase to search for. The text in the phrase must appear in the order passed in. Encode spaces between strings with %20. Text passed with this parameter is case insensitive. Example: http://your_community.lithium.com/restapi/vc/search/ products?phrase=point%20and%20shoot%20camera
one_or_more (optional)	string	A string of one or more search terms to search for, separated by a space. Results match one or more of the terms given. The strings are searched for across all searchable fields. For example, use this if you want to search for a product that contains the term “phone” in its ID, title, or description. Text passed with this parameter is case insensitive. Use OR (case sensitive and encoded with %20 before and after) to search for multiple text strings when you want to search across multiple fields of a product. For example: one_or_more=iPhone%20OR%20Android returns products where either iPhone or Android appear in a field value across all searchable fields. + (AND functionality) is not supported with this parameter. Example: http://your_community.lithium.com/restapi/vc/search/products?one_or_more=phone
without (optional)	string	Search terms to exclude from the result set. The parameter filters out products that contain the term(s) passed. You can use OR between You can use this parameter alone, but we recommend using “without” along with other query parameters to perform faster, more accurate queries. For example, you might search for messages that contain the word "shoe" but pass a particular brand as the value for without. This would return messages about shoes, except for those that mention the specified brand of shoe. Spaces between text strings are interpreted as OR. Text passed with this parameter is case insensitive. Example: http://your_community.lithium.com/restapi/vc/search/products?q=shoe&without=boot Example: http://your_community.lithium.com/restapi/vc/search/products?q=shoe&without=boot mens
sort_by (optional)	string	Determines how to sort the products in the response Possible values: ratingsAverage:review_ratings (for ascending order) –ratingsAverage:review_ratings (for descending order)

Note: The collapse_discussion parameter used with other search APIs is not supported for product searches.

As with other calls, you can use restapi.response_style=view to display the href of the product in the community and restapi.format_detail=full_list_element to return the full list of elements associated with the product, or restapi.format_detail=default to limit the amount of information returned.

For example:

http://your_community.lithium.com/restapi/vc/search/products?phrase=speaker%20phone& restapi.response_style=view&restapi.format_detail=full_list_element

Return replies and comments on messages and product reviews

We have added new calls to the Message and Product resources for Community REST API v1. The calls return direct replies to messages or comments on product reviews. By default, messages are returned ordered by post_date, ascending. A direct reply is a first-level reply made directly to the topic message. A comment is a direct comment made to a product review. To learn more about the Ratings and Reviews feature, read About the Review data model.

APIs to retrieve direct replies to messages

/messages/id/[id]/replies/direct – returns the replies count and message data associated with each reply

/messages/id/[id]/replies/direct/count – returns the number of direct replies

/messages/id/[id]/replies/direct/messages – returns the messages data for each direct reply but does not include the reply count

Example response

http://your_community.lithium.com/restapi/vc/messages/id/92/replies/direct

<response status="successRU">
     <replies type="replies">
         <count type="int">29</count>
         <messages>
               <message type="message" href="/messages/id/151">
                   <subject type="string">test</subject>
                   <post_time type="date_time">2013-08-29T23:42:39+00:00</post_time>
                  <last_edit_time type="date_time">2013-08-29T23:42:39+00:00</last_edit_time>
                   <id type="int">151</id>
                   <read_only type="boolean">false</read_only>
                   <deleted type="boolean">false</deleted>
                   <author type="user" href="/users/id/4">
                         <login type="string">JoeB</login>
                   </author>
                   <thread type="thread" href="/threads/id/92"/>
                   <board type="board" href="/blogs/id/lithiumblog"/>
                   <parent type="message" href="/messages/id/92"/>
                   <teaser type="string"/>
                   <views>
                         <count type="int">206</count>
                  </views>
                   <board_id type="int">5</board_id>
                   <root type="message" href="/messages/id/92"/>
                   <message_rating type="float">0.0</message_rating>
                   <last_edit_author type="user" href="/users/id/4">
                         <login type="string">JoeB</login>
                   </last_edit_author>
                   <kudos>
                         <count type="int">1</count>
                   </kudos>
               </message>
              ...
         </messages>
     </replies>
</response>

APIs to retrieve comments on product reviews

/products/reviews/id/[message_id] – returns the review message

/products/id/[id]/reviews/id/[message_id]/comments – retrieves comments on the specified product review

/products/id/[id]/reviews/id/[message_id]/comments/count – retrieves the number of comments to the specified product review

To find the review ID:

Call /products/id/[id]/reviews/messages to get messages that represent the product reviews:
http://your_community.lithium.com/restapi/vc/products/id/notearth/reviews/messages
Use the ID from the <id> field:

<response status="success">

     <product_review_context type="product_review_context">

     <count type="int">4</count>

     <messages>

         <message type="message" href="/messages/id/954">

         <subject type="string">cj review</subject>

         <post_time type="date_time">2014-10-17T18:53:45+00:00</post_time>

         <last_edit_time type="date_time">2014-10-17T18:53:45+00:00</last_edit_time>

         <id type="int">954</id>

         <read_only type="boolean">false</read_only>

         <deleted type="boolean">false</deleted>

         ...

         </message>

     </messages>

     </product_review_context>

</response>
Pass that ID in one of the /products/id/[id]/reviews/id[message_id] calls:
http://your_community.lithium.com/restapi/vc/products/id/notearth/reviews/id/766/comments

Example response

http://your_community.lithium.com/restapi/vc/products/id/notearth/reviews/id/766/comments

<post_time type="date_time">2014-09-17T21:29:55+00:00</post_time>

<last_edit_time type="date_time">2014-09-17T21:29:55+00:00</last_edit_time>

<board_id type="int">14</board_id>

<read_only type="boolean">false</read_only>

<subject type="string">Re: asdfagawervasdf</subject>

</author>

<deleted type="boolean">false</deleted>

<views>

</views>

<message_rating type="float">0.0</message_rating>

<last_edit_author type="user" href="/users/id/99">

</last_edit_author>

<kudos>

</kudos>

...

</messages>

</comments>

</response>

New response_style parameter options

By default, replies and comments are not included in the message response. We added two new values for restapi.response_style to display replies or comments in message responses. The syntax is:

?restapi.response_style=replies

Displays replies to messages (direct and nested) in message responses. Not supported on /products/id[id]reviews/id/[id]. (Use the comments option instead).

Warning: Use this option sparingly. While the number of messages returned in a response can be limited through pagination, the depth of nested replies is not. Using this option could affect the response time of a search.

?restapi.response_style=comments

Displays comments to product reviews in product responses. Not supported on /messages/id/[id]. (Use the replies option instead.)

Note: The depth of comments on product reviews is limited to direct replies, so you won’t experience any slow down to search response times when using the replies option.

More secure method for setting font sizes in TinyMCE

To close a potential security vulnerability, we have changed the way that TinyMCE sets text sizes in posts. Instead of using font point sizes (8pt, 10pt, 12pt), TinyMCE now uses HTML labels 1-7, referring to the HTML font size attributes instead of the CSS. As such, when you open the Font Sizes menu in TinyMCE, you now see numerical font size options from 1 (smallest) to 7 (largest). These HTML font sizes map to the same font point sizes that were previously available (8, 10, 12, 14,18, 24, 36).

Note: This change was purely precautionary as there have been no known exploits of this vulnerability on a Lithium community. Nonetheless, we made the change as we felt it was best for all users of our software.

We recommend informing your users about this change so they’re not surprised.

You Found It. We Fixed It.

Community Mobile v2 now supports relative dates (for example, three days ago) in all supported languages when you enable Community Admin > System > Date and Time > Use Relative Dates.
We’ve fixed the issue where you could not switch the Community Admin > Content > Custom Content setting after making your first selection.
Previously, when you entered code (for example, a URL) into the rich text editor when posting a message, the code was automatically converted to a link. Now, the code displays as plain text.
When clicking the View all link in the Recent Messages component, the returned messages were not being scoped properly to the discussion style. Now, the Recent Messages displays only the posts scoped to that node.
Special characters are now being displayed properly in the message titles of subscription emails.

The CommunityJsonObject.WebTracking object now escapes '/' characters if they are included as part of a message subject.
Previously, the Create New menu failed to open if all child categories were expanded. This issue has been fixed.

Refer to the attached Known Issues list for an update on open issues that we’re currently investigating.

Updated 5 months ago

Version 18.0

LIA_14_10_KnownIssuesList.xlsx9 KB

communities classic

release notes

JohnD

Khoros Alumni (Retired)

Joined March 14, 2013

View Profile