Showing results for 
Show  only  | Search instead for 
Did you mean: 

Getting Tag Definitions out of SMM

Khoros Guru

Lithium SMM allows an Admin to define any number of tags in a hierarchical structure. Once defined, you may want to examine the tag structure in a spreadsheet.  The admin screen does not allow you to export tags into a spreadsheet, but the product does have a programmatic API to get the tags and get the tag rules for Conversation tags (there isn't currently an API for getting  Author tags rules).

API Documentation Links

That's great to have the APIs, but you need to have a programmer use them to get the data from both and join the results together,

If you can you google docs, you can use this example to get the tag data into a spreadsheet.  If you can't, you can use this as an example.

You can click this link to copy the example into your own Google drive. After you copy it, the copy will be your own  private copy.  It is totally self-contained and you are welcome to use it. Alternatively, you can just use it as an example of use the code sample below.

Using the Sample

Here is a video of how you can use the link above to copy the sample and use it yourself:


The Sample Explained

The sample uses Google App Script - which is javascript with access to objects that let you interact with Google docs as well as external services (in this case, the Lithium API). The code uses the /api/v2/tags endpoint to get all tags, and the /api/v2/tagRuleDefinitions endpoint to get all conversation tag rules (it must paginate through). It them takes those 2 results, joins them together on the tagId, an writes the result to the Curren spreadsheet sheet.

Making the API Calls

Here is the function that makes the API call itself.  The SMM APIs use basic authentication, so you see the code add the authorization header for basic auth.

 * This function does an API call (GET) given a URL, a username, and a password. 
 * If successful, returns the JSON result
 * If not, throws error with the message returned
function doApiGet(url,username,password) {
  var options = 
    { headers: 
      { Authorization: "Basic " + Utilities.base64Encode(username + ":" + password) }
       ,muteHttpExceptions : true //if false, this would throw the HTTP exception. Instead, handle the errpr ourselves.
  var resp = UrlFetchApp.fetch(url,options);
  resp = JSON.parse(resp.getContentText());
  if (resp.status == "success") {
   return resp;
  } else {
   throw resp.message;

Making the api call to get all tags is very straight-forward:

 * This function returns an array of all the tags from a lithium env
 * given a url, username, and password for that environment. It returns
 * the data portion of the API call as outlined here:
function getTags(lithiumUrl,username,password) {
  var options = { headers: { Authorization: "Basic " + Utilities.base64Encode(username + ":" + password) }};
  var resp = doApiGet(lithiumUrl + "/api/v2/tags",username,password);

Getting the Tag Rule Definitions is a little more involved since the results are paginated. If there are more tagRuleDefinitions, you make the call again for the next page.

 * This function returns a map from all tagIds (with at least one rule) to an 
 * array of those rules given a url to lithium, a username, and a password. 
 * The result is of the form:
 *  { <tagId1> : [{<rule1-1>},{<rule1-2>},...]
 *   ,<tagId2> : [{<rule2-1>},{<rule2-2>},...]
 *   ...
 *  }
 * where each rule is of the form outlined here:
function getTagRuleDefinitionsByTagId(lithiumUrl,username,password) {
  var offset = 0;
  var limit = 1000;
  var resp = {};
  var res = {};
  //Since the api is paginated, we need to keep calling the API until
  //  there are no more results. In this case, we'll  call with a page
  //  size of 1000.
  do {
    resp = doApiGet(lithiumUrl + "/api/v2/tagRuleDefinitions?offset=" + offset + "&limit=" + limit,username,password);
    var tagRules =;
    tagRules.forEach(function(tagRule) {
      if (!res[tagRule.tagId]) { res[tagRule.tagId] = []; };
    offset += limit;
  } while (resp["_metadata"].paging.moreContent);
  return res;

That is the heart of the sample, and if you want to see all of it, copy the example and then view the script in the google script editor.

Esteemed Contributor

This is great and might be very useful as we're about to undertake a tag review! @louisamartin

Occasional Contributor

oh wow!!!!! I did this manually!