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.

Procedure

  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).
      {"items":          
                   [{            
                     "userid": "20883125",            
                     "member":"test1@us.ibm.com",            
                     "name":"Test1"           
                    },           
                   {  
                     "userid":"20883126",           
                     "member":"test2@us.ibm.com",           
                     "name":"Test2"          
                   }        
                  ]     
               }
    • 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];                                               
                         idArray.push(id);                                   
                    }                                   
                    if(idArray.length == 0 ) return;                                    
                    var url = getMentionUri();                                    
                    var response,ioArgs;                                    
                    var link = window.location.href;                                    
                    var sData = dojo.toJson({                         
                                 "type":["create"|"reply"],                          
                                 "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 
                          });                                   
                    dojo.xhrPost({                                               
                      url: url,                                               
                      handleAs: "json",                                               
                      handle: function(r, io) {response = r; ioArgs = io;},                                               
                      sync: false,                                               
                      contentType: "text/plain",                                               
                      postData: sData                                    
                 });                                
               }), 500); 
    • The detailed descriptions are:
      type
      There are two kinds of types. One is comment and another is reply.
      author
      The user's id who mentions others in a comment or reply.
      mentionlist
      All id information of mentioned users in a comment or a reply. It is an id's array.
      owner
      The author of the current comment. If the type's value is "comment", the author's value is the same as the owner's.
      link
      The URL of the current Docs file.
      fileid
      The id of the current Docs file.
      filename
      The title information of the current Docs file.
      content
      The content of the comment or reply.
      commentsid
      The unique id of the comment.
  3. How to configure REST endpoint in concord-config.json:
    "ExternalCommentService":           
              {                        
                 "enabled": "true",//enable the configuration                    
                 "apiConfig":                                  
                     {                                               
                          "MentionUsersUri":"/api/comment/{fileid}/getCommentUserList",                                               
                          "MentionNotificationUri":"/api/mention"                                   
                     }           
               },
    Note: The value of MentionUsersUri must contain /{fileid}/.