PrizmDoc Viewer v13.18 Release - Updated
API Reference / PAS REST API / Viewer Support / Markup Burners
In This Topic
    Markup Burners
    In This Topic

    Introduction

    The PAS markup burners REST API is used by our viewer to allow the user to download the document they are viewing as a PDF with all annotations applied.

    This REST API is designed for our viewer. If your application needs to perform its own markup burning, we recommend you use PrizmDoc Server’s markup burners REST API instead. It allows your application to produce PDFs with annotations “burned in” without the need for a viewing session.

    Available URLs

    URL Description
    POST /ViewingSession/u{viewingSessionId}/MarkupBurner Starts a new MarkupBurner using the source document of a viewing session and provided markup data as input.
    GET /ViewingSession/u{viewingSessionId}/MarkupBurner/{processId} Gets the status of a MarkupBurner for a viewing session.
    GET /ViewingSession/u{viewingSessionId}/MarkupBurner/{processId}/Document Gets the output result of a MarkupBurner process for a viewing session.

    POST /ViewingSession/u{viewingSessionId}/MarkupBurner

    Routes key: CreateMarkupBurner

    Starts a new MarkupBurner using the source document of a viewing session and a provided markup data as input. When the asynchronous process is ultimately finished, the output will be a new document which includes the provided markup as part of the document itself (the original source document of the viewing session is left unaltered).

    This is a specialized URL which allows you to do markup burning against the source file of an existing viewing session without needing to use the work file API.

    This request merely begins the markup burning process. Once started, you poll the status of the process using the GET /ViewingSession/u{viewingSessionId}/MarkupBurner/{processId} URL below to know when the process has completed.

    Request

    Request Headers

    Name Description
    Content-Type Specifies the type of content being provided to the markup burner process. It must be application/xml or application/json depending on the markup format used in the request body.

    URL Parameters

    Parameter Description
    {viewingSessionId} The id provided in the response from POST /PCCIS/V1/ViewingSession.

    Query String Parameters

    Parameter Description
    {redactionMode} How redactions should be applied. May be one of the following:
    • "normal" - Actually redact the document, removing document content covered by redactions, drawing opaque redaction rectangles, and drawing any associated redaction reason text in the center of the rectangles.
    • "draft" - Do NOT actually redact the document. Instead, indicate which parts of the document would be redacted by drawing partially transparent redaction rectangles over the parts of the document that would be redacted. In order to avoid interfering with the original document content, redaction reason text will not be drawn in the center of the transparent redaction rectangles.
    Default is "normal".
    {redactionDraftOpacity} Controls the opacity of redactions when redactionMode is set to "draft". Must be a value within 0 and 1 where 0 is fully transparent and 1 is fully opaque. Default is 0.2.
    {RemoveFormFields} Optional parameter indicating which interactive form fields to remove from the source document upon markup burner process. Currently only "acroform" value is supported. Please see example below.

    Request Body

    The JSON or XML markup to burn into the source document.

    Response Body

    If successful, a JSON object which may contain:

    • processId (String) The id of the process.
    • state (String) The current state of the markup burning process running on the server. This will always be "processing" in the initial POST response.
    • percentComplete (Integer) The percentage (0 – 100) complete of the process. This will always be 0 in the initial POST response.
    • input (null) Legacy property which exists only for backwards compatibility. Value will always be null.
    • output (null) Legacy property which exists only for backwards compatibility. Value will always be null.

    Error Responses

    Status Code Description
    404 Not Found, if {viewingSessionId} does not exist.
    405 Method Not Allowed, if POST HTTP method is not used.
    480 An invalid input value was used. See errorDetails in the response body.

    Examples

    Request to burn a rectangle annotation using JSON markup

    POST pas_base_url/ViewingSession/uDLbVh9sTmXJAmd1GeXbS9Gn3WHxs8oib2xPsW2xEFjnIDdoJcudPtxciodSYFQq6zYGabQ_rJIecdbkImTTkSA/MarkupBurner
    Content-Type: application/json
    
    {
      "marks": [
        {
          "uid": "Z2diOV8yMDE3LTAzLTMxVDA3OjQ5OjExLjUyNVpfY2VnNjZy",
          "interactionMode": "Full",
          "pageNumber": 1,
          "type": "RectangleAnnotation",
          "creationDateTime": "2017-03-31T07:49:11.525Z",
          "modificationDateTime": "2017-03-31T07:49:11.526Z",
          "data": {},
          "conversation": {},
          "rectangle": {
            "x": 0,
            "y": 0,
            "width": 0,
            "height": 0
          },
          "pageData": {
            "width": 612,
            "height": 792
          },
          "borderColor": "#000000",
          "borderThickness": 4,
          "fillColor": "#FB0404",
          "opacity": 255
        }
      ]
    }
    
    

    Request to burn a rectangle annotation using JSON markup with removal of acroform fields

    POST prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uDLbVh9sTmXJAmd1GeXbS9Gn3WHxs8oib2xPsW2xEFjnIDdoJcudPtxciodSYFQq6zYGabQ_rJIecdbkImTTkSA/MarkupBurner?RemoveFormFields=acroform
    Content-Type: application/json
    {
      "marks": [
        {
          "uid": "Z2diOV8yMDE3LTAzLTMxVDA3OjQ5OjExLjUyNVpfY2VnNjZy",
          "interactionMode": "Full",
          "pageNumber": 1,
          "type": "RectangleAnnotation",
          "creationDateTime": "2017-03-31T07:49:11.525Z",
          "modificationDateTime": "2017-03-31T07:49:11.526Z",
          "data": {},
          "conversation": {},
          "rectangle": {
            "x": 0,
            "y": 0,
            "width": 0,
            "height": 0
          },
          "pageData": {
            "width": 612,
            "height": 792
          },
          "borderColor": "#000000",
          "borderThickness": 4,
          "fillColor": "#FB0404",
          "opacity": 255
        }
      ]
    }
    
    

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "input": null,
        "processId": "ElkNzWtrUJp4rXI5YnLUgw",
        "state": "processing",
        "percentComplete": 0,
        "errorCode": null,
        "output": null
    }
    
    

    GET /ViewingSession/u{viewingSessionId}/MarkupBurner/{processId}

    Routes key: PollMarkupBurner

    Gets the status of a MarkupBurner for a viewing session.

    Requests are typically sent to this URL repeatedly as long as the state is "processing".

    When state is "complete", a new document with the provided markup burned into it will be available at:

    GET /ViewingSession/u{viewingSessionId}/MarkupBurner/{processId}/Document

    If an error occurred and the output could not be created, the state property will be "error" and the errorCode property will contain an error code string.

    Request

    URL Parameters

    Parameter Description
    {viewingSessionId} The id provided in the response from POST /ViewingSession.
    {processId} The id of the process.

    Response Body

    If successful, a JSON object which may contain:

    • processId (String) The id of the process.
    • state (String) The current state of the process. The following values are allowed:
      • "processing" - The markup burning is in progress.
      • "complete" - The markup burning is completed.
      • "error" - The markup burning returns an error.
    • percentComplete (Integer) The percentage (0 – 100) complete of the process.
    • errorCode (String) An error code string if a problem occurred during processing.
    • input (null) Legacy property which exists only for backwards compatibility. Value will always be null.
    • output (null) Legacy property which exists only for backwards compatibility. Value will always be null.

    Error Responses

    Status Code Description
    404 Not Found, if either the {viewingSessionId} or {processId} do not exist.
    405 Method Not Allowed, if GET method is not used.

    Examples

    Request

    GET pas_base_url/PCCIS/V1/ViewingSession/uDLbVh9sTmXJAmd1GeXbS9Gn3WHxs8oib2xPsW2xEFjnIDdoJcudPtxciodSYFQq6zYGabQ_rJIecdbkImTTkSA/MarkupBurner/5rGUUh3Qxhf6VXm8RkBPfA
    
    

    Response when the state is "processing"

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "input": null,
        "processId": "5rGUUh3Qxhf6VXm8RkBPfA",
        "state": "processing",
        "percentComplete": 0,
        "errorCode": null,
        "output": null
    }
    
    

    Response when the state is "complete"

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "input": null,
        "processId": "5rGUUh3Qxhf6VXm8RkBPfA",
        "state": "complete",
        "percentComplete": 100,
        "errorCode": null,
        "output": null
    }
    
    

    Response when the state is "error" because the provided markup XML did not contain valid XML markup or the provided markup JSON was auto-detected as a non-text format

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "input": null,
        "processId": "53LCkvO8-rsDIaW95WgoFA",
        "state": "error",
        "percentComplete": 0,
        "errorCode": "RedactionError",
        "output": null
    }
    
    

    Response when the state is "error" because the provided markup JSON cannot be parsed as JSON

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "input": null,
        "processId": "53LCkvO8-rsDIaW95WgoFA",
        "state": "error",
        "percentComplete": 0,
        "errorCode": "InvalidJson",
        "output": null
    }
    
    

    Response when the state is "error" because the provided markup JSON does not match the JSON Marks Schema

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "input": null,
        "processId": "53LCkvO8-rsDIaW95WgoFA",
        "state": "error",
        "percentComplete": 0,
        "errorCode": "InvalidMarkup",
        "output": null
    }
    
    

    GET /ViewingSession/u{viewingSessionId}/MarkupBurner/{processId}/Document?ContentDispositionFilename={ContentDispositionFilename}

    Routes key: GetBurnedDocument

    Downloads the resulting burned-in document. It will be served with the correct Content-Type of the document, and using the specified ContentDispositionFilename as the name, along with the correct file extension.

    Request

    URL Parameters

    Parameter Description
    {viewingSessionId} The id provided in the response from POST /ViewingSession.
    {processId} The id of the process which identifies the MarkupBurner task as a string.
    {ContentDispositionFilename} The filename as a URL-encoded string, without extension, to be used in the Content-Disposition response header (the file extension will be appended automatically). The default value is "document".

    Response Headers

    Name Description
    Content-Disposition Specifies 'attachment' disposition, RFC-2183 compatible filename parameter and an RFC-8187 compatible filename* parameter, allowing the use of non-ASCII filenames.
    Content-Type Will be application/pdf.

    Response Body

    The raw bytes of the PDF document with markup burned into it.

    Error Responses

    Status Code Description
    404 Not Found, which may occur if any of the following are true: the MarkupBurner has not completed yet, no such MarkupBurner exists, or no such ViewingSession exists.
    405 Method Not Allowed, if GET method is not used.

    Examples

    Request

    GET pas_base_url/ViewingSession/uDLbVh9sTmXJAmd1GeXbS9Gn3WHxs8oib2xPsW2xEFjnIDdoJcudPtxciodSYFQq6zYGabQ_rJIecdbkImTTkSA/MarkupBurner/ElkNzWtrUJp4rXI5YnLUgw/Document
    
    

    Response

    HTTP/1.1 200 OK
    Content-Type: application/pdf
    Content-Disposition: attachment; filename="Greek____.pdf"; filename*=UTF-8''Greek%CE%91%CE%92%CE%93%CE%94.pdf
    
    <<PDF data>>