Using ExportComments and RenderMark

To assist in exporting comment data, we've added two new social endpoints:  ExportComments and RenderMark.  ExportComments gets all threads and replies from a given document, while RenderMark gets the highlighted area of an annotated comment.  Used together, they can get all the annotations on a document and save them, as in our sample console application

ExportComments

The ExportComments function will return a JSON object containing the following parameters:

{
success:true,
Threads:[{
Comment:"Text of the comment",
 CreatedTime:"2 hours ago",
Frame:undefined,
item:18,
list:"cc168d1c-7098-414b-a8fa-a7b37c03d101",
Location:undefined,
Owner:{
LoginName:"DOMAIN\username"
},
ReplyCount:2,
Type:undefined
},{
Comment:"Text of the annotated comment",
 CreatedTime:"15 minutes ago",
Frame:0,
item:24,
list:"cc168d1c-7098-414b-a8fa-a7b37c03d101",
Location:{
height:424,
width:652,
x:331,
y:1020
},
Owner:{
LoginName:"DOMAIN\username2"
},
ReplyCount:0,
Type:"Elipse"
}],

Replies:[[{
Comment:"Text of the reply",
  CreatedTime:"an hour ago",
item:19,
list:"cc168d1c-7098-414b-a8fa-a7b37c03d101",
Owner:{
LoginName:"DOMAIN\username2"
}
},{
Comment:"Text of another reply",
  CreatedTime:"a minute ago",
item:26,
list:"cc168d1c-7098-414b-a8fa-a7b37c03d101",
Owner:{
LoginName:"DOMAIN\username"
}
}],[]]
}

success:  A boolean indicating if the call was successful or not.  Will be true when document exists.

Threads:  A list holding the threads of the conversation.  Threads are all the comments, excluding the replies.  Each thread contains the following parameters:

  • Comment: The text of the comment
  • CreatedTime: Time since the comment has been created.
  • Frame: If the comment is an annotation, value will be 0 (ellipse) or 1 (rectangle).  Otherwise, null.
  • item: The item id of the comment.
  • list: The GUID of the list holding all social comments.
  • Location: If the comment is an annotation, it will contain the following; otherwise, null.
    • height: Height of the annotation in pixels
    • width: Width of the annotation in pixels
    • x: Horizontal location of the annotation in pixels
    • y: Vertical location of the annotation in pixels
  • Owner: Contains the following:
    • LoginName: Name of the user who wrote the comment
  • ReplyCount: Number of replies to the comment
  • Type: If the comment is an annotation, "Ellipse" or "Rectangle".  Otherwise, null.

Replies: A list holding all replies to all threads.  Each item in the list is a list of replies.  The order of the replies matches the order of the threads (so the third replies list holds the replies to the third thread).  If there are no replies to a thread, the list is empty.  Each reply contains the following parameters:

  • Comment: The text of the comment
  • CreatedTime: Time since the comment has been created, counted from the time ExportComments is run.
  • item: The item id of the comment.
  • list: The GUID of the list holding all social comments.
  • Owner: Contains the following:
    • LoginName: Name of the user who wrote the comment

Please only use the parameters documented here.  Undocumented parameters will not be supported in future releases.

If ExportComments is called on a docRef that does not exists, the following JSON will be generated:

{
success:false,
stackTrace:" at Vizit.Utils.Api.VItem.Resolve()
 at Vizit.Utils.Api.Endpoint.SocialEndpoint.<>c__DisplayClass2f.b__2d()
 at Microsoft.SharePoint.SPSecurity.<>c__DisplayClass4.b__2()
 at Microsoft.SharePoint.Utilities.SecurityContext.RunAsProcess(CodeToRunElevated secureCode)
 at Microsoft.SharePoint.SPSecurity.RunWithElevatedPrivileges(WaitCallback secureCode, Object param)
 at Microsoft.SharePoint.SPSecurity.RunWithElevatedPrivileges(CodeToRunElevated secureCode)
 at Vizit.Utils.Api.Endpoint.SocialEndpoint.ExportComments(VItem docRef)
 at Vizit.Utils.Net.Adapter.Invokers.ReflectedInvoker.Invoke(Object instance, Object[] arguments)
 at Vizit.Utils.Net.Adapter.Invokers.Invoker.Invoke(Object instance, CallContext context)Inner Exception:
----------------
The system cannot find the file specified. (Exception from HRESULT: 0x80070002)
 at Microsoft.SharePoint.Library.SPRequestInternalClass.GetMetadataForUrl(String bstrUrl, Int32 METADATAFLAGS, Guid& pgListId, Int32& plItemId, Int32& plType, Object& pvarFileOrFolder)
 at Microsoft.SharePoint.Library.SPRequest.GetMetadataForUrl(String bstrUrl, Int32 METADATAFLAGS, Guid& pgListId, Int32& plItemId, Int32& plType, Object& pvarFileOrFolder)
 at Microsoft.SharePoint.SPWeb.GetListItem(String strUrl, Boolean bFields, String[] fields)
 at Vizit.Utils.Api.VItem.Resolve()",
message:"The document does not exist. It may have been deleted from the repository."
}

 

RenderMark

The RenderMark function returns an image stream of the desired comment, with some number of surrounding pixels for context.  The function uses the following parameters:

  • docRef: JSON Object, Required. A reference to the top level comment thread that has a highlight on it.
  • boundingBox: Size, Required.  The desired size of the returned image. The resulting image will be fit into the passed box, but will maintain the aspect ratio of the original annotation.
  • padding: int, Optional.  The number of pixels on each side of the annotation, to provide context.  Defaults to 0.  If larger than boundingBox height or width, scales to show as much as possible.
  • showMark: boolean, Optional.  Option to show the highlight.  Defaults to false.

Example

Here is a screenshot of the original image with an ellipse highlight shown in the upper right.

original.PNG

400x400 image, no buffer, no highlight

http://path/to/site/_layouts/vizit/vizit.core/endpoints/socialendpoint.ashx?op=RenderMark&docRef={"list":"C5320CDD-90B8-48bd-8605-D186DD717209","item":1}&boundingBox={"width":400,"height":400}

example2.png

 400x400 image, no buffer, highlight

http://path/to/site/_layouts/vizit/vizit.core/endpoints/socialendpoint.ashx?op=RenderMark&docRef={"list":"C5320CDD-90B8-48bd-8605-D186DD717209","item":1}&boundingBox={"width":400,"height":400}&showMark=true

example4.PNG

400x400 image, buffer of 20, highlight

http://path/to/site/_layouts/vizit/vizit.core/endpoints/socialendpoint.ashxop=RenderMark&docRef={"list":"C5320CDD-90B8-48bd-8605-D186DD717209","item":1}&boundingBox={"width":400,"height":400}&padding=20&showMark=true

example5.PNG

Comment that does not have an annotation

http://path/to/site/_layouts/vizit/vizit.core/endpoints/socialendpoint.ashx?op=RenderMark&docRef={"list":"C5320CDD-90B8-48bd-8605-D186DD717209","item":1}&boundingBox={"width":400,"height":400}
Vizit.Shared.VizitException: This comment is not an annotation
   at Vizit.Utils.Api.Endpoint.SocialEndpoint.<>c__DisplayClass37.b__36()
   at Microsoft.SharePoint.SPSecurity.<>c__DisplayClass4.b__2()
   at Microsoft.SharePoint.Utilities.SecurityContext.RunAsProcess(CodeToRunElevated secureCode)
   at Microsoft.SharePoint.SPSecurity.RunWithElevatedPrivileges(WaitCallback secureCode, Object param)
   at Microsoft.SharePoint.SPSecurity.RunWithElevatedPrivileges(CodeToRunElevated secureCode)
   at Vizit.Utils.Api.Endpoint.SocialEndpoint.RenderMark(VItem docRef, Nullable`1 threadId, Size boundingBox, Int32 bufferSize, Boolean showHighlight)
   at Vizit.Utils.Net.Adapter.Invokers.ReflectedInvoker.Invoke(Object instance, Object[] arguments)
   at Vizit.Utils.Net.Adapter.Invokers.Invoker.Invoke(Object instance, CallContext context)   at Vizit.Utils.Api.Endpoint.SocialEndpoint.<>c__DisplayClass37.b__36()
   at Microsoft.SharePoint.SPSecurity.<>c__DisplayClass4.b__2()
   at Microsoft.SharePoint.Utilities.SecurityContext.RunAsProcess(CodeToRunElevated secureCode)
   at Microsoft.SharePoint.SPSecurity.RunWithElevatedPrivileges(WaitCallback secureCode, Object param)
   at Microsoft.SharePoint.SPSecurity.RunWithElevatedPrivileges(CodeToRunElevated secureCode)
   at Vizit.Utils.Api.Endpoint.SocialEndpoint.RenderMark(VItem docRef, Nullable`1 threadId, Size boundingBox, Int32 bufferSize, Boolean showHighlight)
   at Vizit.Utils.Net.Adapter.Invokers.ReflectedInvoker.Invoke(Object instance, Object[] arguments)
   at Vizit.Utils.Net.Adapter.Invokers.Invoker.Invoke(Object instance, CallContext context)

 

Sample Console Application

This application will ask for the location of the document, as well as the site that the document is located at.  It will then give an option to export the annotated comments as .png files.  The files will be saved in the same directory as the console application was run from. Each file's name will consist of the annotation number, an underscore, and the original file name. 

The console application is attached. 

Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk