PrizmDoc Viewer v13.17 - Updated
API Reference / PAS REST API / Viewer Support / Markup XML
In This Topic
    Markup XML
    In This Topic

    Introduction

    The markup XML REST API is used by our viewer to save and load markup (annotations and redactions) in our legacy XML format.

    Background

    Our viewer has two different markup persistence modes it operates in:

    • Legacy XML markup mode - In this mode, the viewer saves and loads markup data in our older, legacy XML format using this markup XML REST API. This is the default viewer behavior.
    • JSON markup mode - In this mode, the viewer saves and loads markup data in our newer JSON format using the markup layers REST API. This mode applies when the viewer is configured with annotationsMode set to 'LayeredAnnotations' (recommended).

    We recommend you always instantiate the viewer with annotationsMode set to 'LayeredAnnotations' so that it will operate in the new JSON markup mode. When you do this, the viewer will NOT use this REST API but will instead use this markup layers REST API to save and load markup data in our newer JSON format.

    However, if your application is already using the viewer in the legacy XML markup mode and you need to access or manipulate the markup XML created by your end users, you will need to use this REST API.

    A set of markup data is accessed by markupId. But, because this REST API was designed for use by our viewer, all operations are based upon a viewing session. In order to get access to a set of markup data by markupId, you first must create a “dummy” viewing session, specifying the markupId you want to access via the source.markupId property of your POST /ViewingSession request.

    However, because source.markupId is optional when creating a viewing session, you may not know the markupId to use. Fortunately, as long as you still know the information about the source document and how you created the original viewing session for your end user, there is still a way to access the markup data. When a viewing session is created without a source.markupId specified, we will automatically calculate a markupId value based upon the other source object properties. So, if your did not specify an explicit source.markupId when creating the original viewing session for your end user, you can still access the markup data that end user saved by creating a new “dummy” viewing session with exactly the same set of source properties. For more information about the source object options you can pass in on a POST /ViewingSession request, see the POST /ViewingSession API reference.

    Available URLs

    URL Description
    GET /AnnotationList/q/Art/q Gets the list of available annotation XML files from the server.
    GET /Document/q/Art/q Gets a specific annotations XML file from the server.
    POST /Document/q/Art/q Creates a new annotations XML file using the provided data.

    GET /AnnotationList/q/Art/q?DocumentID=u{viewingSessionId}

    Routes key: GetAnnotations

    Gets the list of available annotation XML files from the server.

    GET pas_base_url/AnnotationList/q/Art/q?DocumentID=u1234
    

    Successful Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "annotationFiles": [
            {
                "annotationLabel": "anId",
                "annotationName": "abcd_0_anId.xml",
                "ID": "1"
            }
        ]
    }
    
    

    Error Responses

    When the server's license could not be verified:

    HTTP/1.1 480 LicenseCouldNotBeVerified
    Content-Type: application/json
    
    {
        "errorCode": "LicenseCouldNotBeVerified"
    }
    
    

    GET /Document/q/Art/q?DocumentID=u{viewingSessionId}&AnnotationID=u{annotationId}

    Routes key: GetAnnotation

    Gets a specific annotations XML file from the server.

    GET pas_base_url/Document/q/Art/q?DocumentID=u1234&AnnotationID=uanId
    

    Successful Response

    HTTP/1.1 200 OK
    Content-Type: application/xml
    
    <?xml version="1.0"?>...
    
    

    Error Responses

    When the server's license could not be verified:

    HTTP/1.1 480 LicenseCouldNotBeVerified
    Content-Type: application/json
    
    {
        "errorCode": "LicenseCouldNotBeVerified"
    }
    
    

    POST /Document/q/Art/q?DocumentID=u{viewingSessionId}&AnnotationID=u{annotationId}

    Routes key: CreateAnnotation

    Creates a new annotations XML file using the provided data.

    POST pas_base_url/Document/q/Art/q?DocumentID=u1234&AnnotationID=uanotherId
    Content-Type: application/xml
    
    <?xml version="1.0">...
    

    Successful Response

    HTTP/1.1 200 OK
    
    

    Error Responses

    When the server's license could not be verified:

    HTTP/1.1 480 LicenseCouldNotBeVerified
    Content-Type: application/json
    
    {
        "errorCode": "LicenseCouldNotBeVerified"
    }