com.veeva.vault.vapil.api.request

Class DocumentAnnotationRequest

java.lang.Object

com.veeva.vault.vapil.api.request.VaultRequest<DocumentAnnotationRequest>

com.veeva.vault.vapil.api.request.DocumentAnnotationRequest

public class DocumentAnnotationRequest
extends VaultRequest<DocumentAnnotationRequest>

Document Annotation Requests

Vault API Coverage:

https://developer.veevavault.com/api/24.1/#document-annotations

Field Summary

Fields inherited from class com.veeva.vault.vapil.api.request.VaultRequest

HTTP_HEADER_AUTHORIZATION, HTTP_HEADER_REFERENCE_ID, HTTP_HEADER_VAULT_CLIENT_ID, referenceId, vaultClient

Method Summary

Modifier and Type	Method and Description
DocumentAnnotationDeleteResponse	deleteAnnotations() Delete Annotations
VaultResponse	exportDocumentAnnotationsToPdf(int docId) Export Document Annotations to PDF
VaultResponse	exportDocumentVersionAnnotationsToPdf(int docId, int majorVersion, int minorVersion) Export Document Version Annotations to PDF
DocumentAnnotationResponse	importDocumentAnnotationsFromPdf(int docId) Import Document Annotations from PDF
DocumentAnnotationResponse	importDocumentVersionAnnotationsFromPdf(int docId, int majorVersion, int minorVersion) Import Document Version Annotations from PDF Load annotations from a PDF to Vault.
DocumentAnnotationReadResponse	readAnnotationsByDocumentVersionAndType(int docId, int majorVersion, int minorVersion) Read Annotations by Document Version and Type Retrieve annotations from a specific document version.
DocumentAnnotationReadResponse	readAnnotationsByDocumentVersionAndTypeByPage(String pageUrl) Read Annotations by Document Version and Type (By Page)
DocumentAnnotationReadResponse	readAnnotationsById(int docId, int majorVersion, int minorVersion, int annotationId) Read Annotations by ID
DocumentAnnotationReplyReadResponse	readRepliesOfParentAnnotation(int docId, int majorVersion, int minorVersion, int annotationId) Read Replies of Parent Annotation Given a parent annotation ID, retrieves all replies to the annotation.
DocumentAnnotationReplyReadResponse	readRepliesOfParentAnnotationByPage(String pageUrl) Read Replies of Parent Annotation (By Page)
DocumentAnnotationResponse	retrieveAnchorIds(int docId) Retrieve Anchor IDs
VaultResponse	retrieveDocumentVersionNotesAsCSV(int docId, int majorVersion, int minorVersion) Retrieve Document Version Notes as CSV Retrieve notes in CSV format for any document that has a viewable rendition and at least one annotation.
VaultResponse	retrieveVideoAnnotations(int docId, int majorVersion, int minorVersion) Retrieve Video Annotations Retrieve annotations on a video document.
DocumentAnnotationRequest	setAnnotationTypes(Set<String> annotationTypes) The type(s) of annotations to retrieve.
DocumentAnnotationRequest	setBinaryFile(String filename, byte[] binaryContent) Specify source data in an input file
DocumentAnnotationRequest	setContentTypeCsv() Set the Header Content Type to CSV
DocumentAnnotationRequest	setContentTypeJson() Set the Header Content Type to JSON
DocumentAnnotationRequest	setInputPath(String inputPath) Specify source data in an input file
DocumentAnnotationRequest	setLimit(Integer limit) This parameter paginates the results by specifying the maximum number of records per page in the response.
DocumentAnnotationRequest	setOffset(Integer offset) This parameter is used to paginate the results.
DocumentAnnotationRequest	setOutputPath(String outputPath) Specify source data in an output file
DocumentAnnotationRequest	setPaginationId(String paginationId) A unique identifier used to load requests with paginated results.
DocumentAnnotationRequest	setRequestString(String requestString) Specify source data in an input string, such as a JSON request

Methods inherited from class com.veeva.vault.vapil.api.request.VaultRequest

getBaseObjectMapper, send, send, sendReturnBinary, sendReturnBinary, sendToFile, sendToFile, setHeaderReferenceId, setVaultClient

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

exportDocumentAnnotationsToPdf

public VaultResponse exportDocumentAnnotationsToPdf(int docId)

Export Document Annotations to PDF

Export the latest version of any document, along with its annotations, as an annotated PDF. This is equivalent to the Export Annotations action in the Vault document viewer UI.

Parameters:

docId - The document id field value.

Returns:

VaultResponse

Vault API Endpoint:

 GET /api/{version}/objects/documents/{doc_id}/annotations/file

Vault API Help Link:

https://developer.veevavault.com/api/24.1/#retrieve-document-annotations

Example Request:

 Example 1 - Bytes
 VaultResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
                .exportDocumentAnnotationsToPdf(docId);

 Example 2 - File
 VaultResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
                .setOutputPath(outputPath)
                .exportDocumentAnnotationsToPdf(docId);
 

Example Response:

 Example 1 - Bytes
 byte[] bytes = response.getBinaryContent();

 Example 2 - File
 System.out.println("Output file: " + response.getOutputFilePath());
 

exportDocumentVersionAnnotationsToPdf

public VaultResponse exportDocumentVersionAnnotationsToPdf(int docId,
                                                           int majorVersion,
                                                           int minorVersion)

Export Document Version Annotations to PDF

Export a specific version of any document, along with its annotations, as an annotated PDF. This is equivalent to the Export Annotations action in the Vault document viewer UI.

Parameters:

docId - The Document Id

majorVersion - The document major_version_number__v field value

minorVersion - The document minor_version_number__v field value

Returns:

VaultResponse

Vault API Endpoint:

 GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/annotations/file

Vault API Help Link:

https://developer.veevavault.com/api/24.1/#retrieve-document-version-annotations

Example Request:

 Example 1 - Bytes
 VaultResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
                .exportDocumentVersionAnnotationsToPdf(docId, majorVersionNumber, minorVersionNumber);

 Example 2 - File
 VaultResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
                .setOutputPath(outputPath)
                .exportDocumentVersionAnnotationsToPdf(docId, majorVersionNumber, minorVersionNumber);
 

Example Response:

 Example 1 - Bytes
 byte[] bytes = response.getBinaryContent();

 Example 2 - File
 System.out.println("Output file: " + response.getOutputFilePath());
 

retrieveAnchorIds

public DocumentAnnotationResponse retrieveAnchorIds(int docId)

Retrieve Anchor IDs

Retrieve all anchor IDs from a document.

Parameters:

docId - The document id field value.

Returns:

DocumentAnnotationResponse

Vault API Endpoint:

 GET /api/{version}/objects/documents/{doc_id}/anchors

Vault API Help Link:

https://developer.veevavault.com/api/24.1/#retrieve-anchor-ids

Example Request:

 DocumentAnnotationResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
                                .retrieveAnchorIds(docId);

Example Response:

 System.out.println(response.getResponse());

 if (response.isSuccessful()) {
   for (DocumentAnnotationResponse.AnchorData data : response.wgetAnchorDataList()) {
     System.out.println("\n**** Data Item **** ");
     System.out.println("anchorId = " + data.getAnchorId());
     System.out.println("noteId = " + data.getNoteId());
     System.out.println("anchorName = " + data.getAnchorName());
     System.out.println("noteAuthor = " + data.getNoteAuthor());
     System.out.println("noteTimestamp = " + data.getNoteTimestamp());
     System.out.println("pageNumber = " + data.getPageNumber());
   }
 }

retrieveDocumentVersionNotesAsCSV

public VaultResponse retrieveDocumentVersionNotesAsCSV(int docId,
                                                       int majorVersion,
                                                       int minorVersion)

Retrieve Document Version Notes as CSV
Retrieve notes in CSV format for any document that has a viewable rendition and at least one annotation. You must have a Full User license type.

Parameters:

docId - The Document Id

majorVersion - The document major_version_number__v field value

minorVersion - The document minor_version_number__v field value

Returns:

VaultResponse

Vault API Endpoint:

 GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/doc-export-annotations-to-csv

Vault API Help Link:

https://developer.veevavault.com/api/24.1/#retrieve-document-version-notes-as-csv

Example Request:

 Example 1 - To File
 VaultResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
                                .setOutputPath(outputPath.toString())
                                .retrieveDocumentVersionNotesAsCSV(docId, majorVersion, minorVersion);

,

 Example 2 - Get the file and manually download (retrieve the file as bytes in the response)
 VaultResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
                        .setOutputPath(null)
                        .retrieveDocumentVersionNotesAsCSV(docId, majorVersion, minorVersion);

Example Response:

 if (response.getResponseStatus().equals(VaultResponse.HTTP_RESPONSE_SUCCESS)) {
   try (OutputStream os = new FileOutputStream(outputPath.toString())) {
     os.write(response.getBinaryContent());
   }
   catch (IOException ignored) {}
 }

 System.out.println("File was saved to: " + response.getOutputFilePath());

retrieveVideoAnnotations

public VaultResponse retrieveVideoAnnotations(int docId,
                                              int majorVersion,
                                              int minorVersion)

Retrieve Video Annotations
Retrieve annotations on a video document.

Parameters:

docId - The Document Id

majorVersion - The document major_version_number__v field value

minorVersion - The document minor_version_number__v field value

Returns:

VaultResponse

Vault API Endpoint:

 GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/export-video-annotations

Vault API Help Link:

https://developer.veevavault.com/api/24.1/#retrieve-video-annotations

Example Request:

 VaultResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
                                .setOutputPath(outputPath.toString())
                                .retrieveVideoAnnotations(docId, majorVersion, minorVersion);
 

importDocumentAnnotationsFromPdf

public DocumentAnnotationResponse importDocumentAnnotationsFromPdf(int docId)

Import Document Annotations from PDF

Load annotations from a PDF to Vault. This is equivalent to the Import Annotations action in the Vault document viewer UI.

Parameters:

docId - The document id field value.

Returns:

DocumentAnnotationResponse

Vault API Endpoint:

 POST /api/{version}/objects/documents/{doc_id}/annotations/file

Vault API Help Link:

https://developer.veevavault.com/api/24.1/#upload-document-annotations

Example Request:

 DocumentAnnotationResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
                .setInputPath(PATH_ANNOTATIONS_FILE)
                .importDocumentAnnotationsFromPdf(docId);
 

Example Response:

 System.out.println("New Annotations: " + response.getNewCount());
 System.out.println("Replies: " + response.getReplies());
 System.out.println("Failures: " + response.getFailures());
 

importDocumentVersionAnnotationsFromPdf

public DocumentAnnotationResponse importDocumentVersionAnnotationsFromPdf(int docId,
                                                                          int majorVersion,
                                                                          int minorVersion)

Import Document Version Annotations from PDF
Load annotations from a PDF to Vault. This is equivalent to the Import Annotations action in the Vault document viewer UI.

Parameters:

docId - The Document Id

majorVersion - The document major_version_number__v field value

minorVersion - The document minor_version_number__v field value

Returns:

DocumentAnnotationResponse

Vault API Endpoint:

 POST /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/annotations/file

Vault API Help Link:

https://developer.veevavault.com/api/24.1/#upload-document-version-annotations

Example Request:

 DocumentAnnotationResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
                .setInputPath(PATH_ANNOTATIONS_FILE)
                .importDocumentVersionAnnotationsFromPdf(docId, majorVersionNumber, minorVersionNumber);
 

Example Response:

 System.out.println("New Annotations: " + response.getNewCount());
 System.out.println("Replies: " + response.getReplies());
 System.out.println("Failures: " + response.getFailures());
 

readAnnotationsByDocumentVersionAndType

public DocumentAnnotationReadResponse readAnnotationsByDocumentVersionAndType(int docId,
                                                                              int majorVersion,
                                                                              int minorVersion)

Read Annotations by Document Version and Type
Retrieve annotations from a specific document version. You can retrieve all annotations or choose to retrieve only certain annotation types.

Parameters:

docId - The Document Id

majorVersion - The document major_version_number__v field value

minorVersion - The document minor_version_number__v field value

Returns:

DocumentAnnotationReadResponse

Vault API Endpoint:

 POST GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/annotations

Vault API Help Link:

https://developer.veevavault.com/api/24.1/#read-annotations-by-document-version-and-type

Example Request:

 DocumentAnnotationReadResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
                .readAnnotationsByDocumentVersionAndType(docId, majorVersionNumber, minorVersionNumber);
 

Example Response:

 List<DocumentAnnotation> annotations = response.getData();
 for (DocumentAnnotation annotation : annotations) {
                        System.out.println("Annotation ID: " + annotation.getId());
                        System.out.println("Comment: " + annotation.getComment());
                        System.out.println("Type: " + annotation.getType());
 }
 

readAnnotationsByDocumentVersionAndTypeByPage

public DocumentAnnotationReadResponse readAnnotationsByDocumentVersionAndTypeByPage(String pageUrl)

Read Annotations by Document Version and Type (By Page)

Retrieve annotations from a specific document version using the previous_page or next_page parameter of a previous request

Parameters:

pageUrl - The URL from the previous_page or next_page parameter

Returns:

DocumentAnnotationReadResponse

Vault API Endpoint:

 GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/annotations

Vault API Help Link:

https://developer.veevavault.com/api/24.1/#read-annotations-by-document-version-and-type

Example Request:

 if (response.isPaginated()) {
      String nextPageUrl = response.getResponseDetails().getNextPage();
      DocumentAnnotationReadResponse response_page_2 = vaultClient.newRequest(DocumentAnnotationRequest.class)
          .readAnnotationsByDocumentVersionAndTypeByPage(nextPageUrl);
 

Example Response:

 List<DocumentAnnotation> annotations = response_page_2.getData();
 for (DocumentAnnotation annotation : annotations) {
      System.out.println("Annotation ID: " + annotation.getId());
      System.out.println("Comment: " + annotation.getComment());
      System.out.println("Type: " + annotation.getType());
 }
 

readAnnotationsById

public DocumentAnnotationReadResponse readAnnotationsById(int docId,
                                                          int majorVersion,
                                                          int minorVersion,
                                                          int annotationId)

Read Annotations by ID

Retrieve a specific annotation by the annotation ID.

Parameters:

docId - The Document Id

majorVersion - The document major_version_number__v field value

minorVersion - The document minor_version_number__v field value

annotationId - The annotation id

Returns:

DocumentAnnotationReadResponse

Vault API Endpoint:

 GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/annotations/{annotation_id}

Vault API Help Link:

https://developer.veevavault.com/api/24.1/#read-annotations-by-id

Example Request:

 DocumentAnnotationReadResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
      .readAnnotationsById(docId, majorVersionNumber, minorVersionNumber, annotationId);
 

Example Response:

 List<DocumentAnnotation> annotations = response.getData();
 for (DocumentAnnotation annotation : annotations) {
      System.out.println("Annotation ID: " + annotation.getId());
      System.out.println("Comment: " + annotation.getComment());
      System.out.println("Type: " + annotation.getType());
 }
 

readRepliesOfParentAnnotation

public DocumentAnnotationReplyReadResponse readRepliesOfParentAnnotation(int docId,
                                                                         int majorVersion,
                                                                         int minorVersion,
                                                                         int annotationId)

Read Replies of Parent Annotation
Given a parent annotation ID, retrieves all replies to the annotation.

Parameters:

docId - The Document Id

majorVersion - The document major_version_number__v field value

minorVersion - The document minor_version_number__v field value

annotationId - The annotation id

Returns:

DocumentAnnotationReplyReadResponse

Vault API Endpoint:

 GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/annotations/{annotation_id}/replies

Vault API Help Link:

https://developer.veevavault.com/api/24.1/#read-replies-of-parent-annotation

Example Request:

 DocumentAnnotationReplyReadResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
      .readRepliesOfParentAnnotation(docId, majorVersionNumber, minorVersionNumber, annotationId);
 

Example Response:

 List<DocumentAnnotationReply> replies = response.getData();
 for (DocumentAnnotationReply reply : replies) {
      System.out.println("ID: " + reply.getId());
      System.out.println("Comment: " + reply.getComment());
      System.out.println("Type: " + reply.getType());
 }
 

readRepliesOfParentAnnotationByPage

public DocumentAnnotationReplyReadResponse readRepliesOfParentAnnotationByPage(String pageUrl)

Read Replies of Parent Annotation (By Page)

Retrieve replies from a specific annotation using the previous_page or next_page parameter of a previous request

Parameters:

pageUrl - The URL from the previous_page or next_page parameter

Returns:

DocumentAnnotationReplyReadResponse

Vault API Endpoint:

 GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/annotations/{annotation_id}/replies

Vault API Help Link:

https://developer.veevavault.com/api/24.1/#read-replies-of-parent-annotation

Example Request:

 if (response.isPaginated()) {
      String nextPageUrl = response.getResponseDetails().getNextPage();
      DocumentAnnotationReplyReadResponse response_page_2 = vaultClient.newRequest(DocumentAnnotationRequest.class)
          .readRepliesOfParentAnnotationByPage(nextPageUrl);
 

Example Response:

 List<DocumentAnnotationReply> replies = response_page_2.getData();
 for (DocumentAnnotationReply reply : replies) {
      System.out.println("ID: " + reply.getId());
      System.out.println("Comment: " + reply.getComment());
      System.out.println("Type: " + reply.getType());
 }
 

deleteAnnotations

public DocumentAnnotationDeleteResponse deleteAnnotations()

Delete Annotations

Delete multiple annotations. You can delete up to 500 annotations per batch.

Returns:

DocumentAnnotationDeleteResponse

Vault API Endpoint:

 DELETE/api/{version}/objects/documents/annotations/batch

Vault API Help Link:

https://developer.veevavault.com/api/24.1/#delete-annotations

Example Request:

 Example 1 - CSV input
 DocumentAnnotationDeleteResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
      .setContentTypeCsv()
      .setInputPath(csvFilePath)
      .deleteAnnotations();

 Example 2 - Binary input
 DocumentAnnotationDeleteResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
      .setContentTypeCsv()
      .setBinaryFile(csvFile.getName(), Files.readAllBytes(csvFile.toPath()))
      .deleteAnnotations();

 Example 3 - Json input
 DocumentAnnotationDeleteResponse response = vaultClient.newRequest(DocumentAnnotationRequest.class)
      .setContentTypeJson()
      .setRequestString(requestString)
      .deleteAnnotations();
 

Example Response:

 List<DeletedAnnotation> deletedAnnotations = response.getData();
 for (DeletedAnnotation deletedAnnotation : deletedAnnotations) {
      System.out.println("Annotation ID: " + deletedAnnotation.getAnnotationId());
      System.out.println("Doc Id: " + deletedAnnotation.getDocumentId());
      System.out.println("Major Version: " + deletedAnnotation.getMajorVersion());
      System.out.println("Minor Version: " + deletedAnnotation.getMinorVersion());
 }
 

setBinaryFile

public DocumentAnnotationRequest setBinaryFile(String filename,
                                               byte[] binaryContent)

Specify source data in an input file

Parameters:

filename - file name (no path)

binaryContent - byte array of the file content

Returns:

DocumentAnnotationRequest

setInputPath

public DocumentAnnotationRequest setInputPath(String inputPath)

Specify source data in an input file

Parameters:

inputPath - Absolute path to the file for the request

Returns:

DocumentAnnotationRequest

setOutputPath

public DocumentAnnotationRequest setOutputPath(String outputPath)

Specify source data in an output file

Parameters:

outputPath - Absolute path to the file for the response

Returns:

DocumentAnnotationRequest

setOffset

public DocumentAnnotationRequest setOffset(Integer offset)

This parameter is used to paginate the results. It specifies the amount of offset from the first record returned.

Parameters:

offset - Amount of offset from the first record returned

Returns:

DocumentAnnotationRequest

setLimit

public DocumentAnnotationRequest setLimit(Integer limit)

This parameter paginates the results by specifying the maximum number of records per page in the response.

Parameters:

limit - Max number of results

Returns:

DocumentAnnotationRequest

setPaginationId

public DocumentAnnotationRequest setPaginationId(String paginationId)

A unique identifier used to load requests with paginated results.

Parameters:

paginationId - The pagination id

Returns:

DocumentAnnotationRequest

setAnnotationTypes

public DocumentAnnotationRequest setAnnotationTypes(Set<String> annotationTypes)

The type(s) of annotations to retrieve. For example, note__sys,anchor__sys. If omitted, Vault returns all annotations.

Parameters:

annotationTypes - A set of annotation types

Returns:

DocumentAnnotationRequest

setContentTypeCsv

public DocumentAnnotationRequest setContentTypeCsv()

Set the Header Content Type to CSV

Returns:

DocumentAnnotationRequest

setContentTypeJson

public DocumentAnnotationRequest setContentTypeJson()

Set the Header Content Type to JSON

Returns:

DocumentAnnotationRequest

setRequestString

public DocumentAnnotationRequest setRequestString(String requestString)

Specify source data in an input string, such as a JSON request

Parameters:

requestString - The source request as a string

Returns:

DocumentAnnotationRequest