Using comments API for third-party integration

• 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.

• 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.

"ExternalCommentService":           
          {                        
             "enabled": "true",//enable the configuration                    
             "apiConfig":                                  
                 {                                               
                      "MentionUsersUri":"/api/comment/{fileid}/getCommentUserList",                                               
                      "MentionNotificationUri":"/api/mention"                                   
                 }           
           },