Using comments API for third-party integration

If you have already applied IBM Docs 2.0 CR2 or later versions, in third-party integrations, you can implement two RESTful APIs to enable the IBM Docs comments service. The REST endpoint is able to be configured in the Docs configuration file concord-config.json.

About this task

IBM Docs supports the integration with third-party repositories with many security authentication strategies. If Cookies is used to authenticate during the integration, REST API cannot be cross-domain.


  1. When users type @ in a Docs comment or reply, the mention widget will list all available users fetched from the third party by the REST API. The REST API is similar to: GET http(s)://domain/api/comment/{fileid}/getCommentUserList
    • Docs client invokes the REST API so as to get all users with Edit privilege.
    • The response of this REST API returns the following sample data, which includes the userid, member(user's email), and name(user's displaying name).
                     "userid": "20883125",            
    • Only editors are able to co-edit a Docs file and only the owner of the Docs file has the privilege to share the edit privilege to other co-editors. Therefore, you cannot expect to list users without Edit privilege first and then share Edit privilege and mention them.
  2. When creating a comment, adding a reply to a comment or mention users in a comment or reply, Docs needs to notify the third party of the change. Following is the sample REST API for this change: POST http(s)://domain/api/mention
    • Docs client invokes dojo.xhrPost to send the data to the Third Party. Following is the sample code snippet.
      setTimeout(dojo.hitch(this, function(){                                                                
                    var idArray = new Array();                                    
                    for(var i=0;i< mentions.length; i++){                                               
                         var id = mentions[i];                                               
                    if(idArray.length == 0 ) return;                                    
                    var url = getMentionUri();                                    
                    var response,ioArgs;                                    
                    var link = window.location.href;                                    
                    var sData = dojo.toJson({                         
                                 "author": userid,  //who makes this action                         
                                 "mentionList": [id1, id2,id3], //[option]; only for mention 
                                 "owner": who creates this comment // it will be identical to 'author' when//type is create                         
                                 "link": link, //url link                                   
                                 "fileid": uri, // file id                                        
                                 "filename":  title, // file's title                         
                                 "content": content // comment content or reply content
                                 "commentsid": comments id // the uuid of this comments 
                      url: url,                                               
                      handleAs: "json",                                               
                      handle: function(r, io) {response = r; ioArgs = io;},                                               
                      sync: false,                                               
                      contentType: "text/plain",                                               
                      postData: sData                                    
               }), 500); 
    • The detailed descriptions are:
      There are two kinds of types. One is comment and another is reply.
      The user's id who mentions others in a comment or reply.
      All id information of mentioned users in a comment or a reply. It is an id's array.
      The author of the current comment. If the type's value is "comment", the author's value is the same as the owner's.
      The URL of the current Docs file.
      The id of the current Docs file.
      The title information of the current Docs file.
      The content of the comment or reply.
      The unique id of the comment.
  3. How to configure REST endpoint in concord-config.json:
                 "enabled": "true",//enable the configuration                    
    Note: The value of MentionUsersUri must contain /{fileid}/.