PrizmDoc Viewer v13.12 Release - Updated
Developer Guide / PrizmDoc Server / Markup Burner XML Specification
In This Topic
    Markup Burner XML Specification
    In This Topic

    Introduction

    A user can provide a specification of required modifications to a document in an XML-based format. The following nodes are expected as part of the declaration:

    <?xml version="1.0"?>
    <documentAnnotations>
        <pages>
            <page id="1" pageWidth="612" pageHeight="792"></page>
        </pages>
    </documentAnnotations>
    
    

    A <pages> element can contain a number of <page> elements, each containing an arbitrary number of the <annotation> elements. Each <page> element must have the following attributes:

    Name Type Required Description
    id integer yes A 1-based page number; annotations that are listed as child elements of a given <page> are only applied to the corresponding page of the target document.
    pageWidth floating point yes Page width. This attribute is only used for positioning of annotations which use absolute coordinates (such as <line-rectangles> data in text_hyperlink_annotation). This value can be arbitrary, as long as absolute coordinates specified in annotations are consistent with it.
    pageHeight floating point yes Page height. This attribute is only used for positioning of annotations which use absolute coordinates (such as <line-rectangles> data in text_hyperlink_annotation). This value can be arbitrary, as long as absolute coordinates specified in annotations are consistent with it.

    Each <page> can contain an arbitrary number of the <annotation> elements.

    Each <annotation> element defines a certain modification to a page content. A specific set of attributes depends on drawType attribute of the <annotation>.

    Common Attributes

    Each <annotation> element supports the following attribute set:

    Name Type Required / Default Description
    drawType string yes One of the supported draw types (see Draw Type Descriptions below) that defines what modification should an annotation apply to a page.
    x_percent float 0.0 X position of a bounding rectangle, in 0-to-1 based portion of a page width.
    y_percent float 0.0 Y position of a rectangle, in 0-to-1 based portion of a page height.
    width_percent float 0.0 Width of a bounding rectangle, in 0-to-1 based portion of a page width.
    height_percent float 0.0 Height position of a rectangle, in 0-to-1 based portion of a page height.

    The set of x_percent, y_percent, width_percent, height_percent coordinates is referred to as a “bounding rectangle” in the draw type descriptions below.

    Example XML

    Below is a full working sample of a redaction XML containing one annotation for the 1st page that adds a black rectangle redaction to a redacted document:

    &lt;?xml version="1.0"?&gt;
    &lt;documentAnnotations&gt;
        &lt;pages&gt;
            &lt;page id="1" pageWidth="612" pageHeight="792"&gt;
                &lt;annotation drawType="rectangle_filled_redact"
                    x_percent="0.043" y_percent="0.028"
                    height_percent="0.093" width_percent="0.128" /&gt;
            &lt;/page&gt;
        &lt;/pages&gt;
    &lt;/documentAnnotations&gt;
    
    

    Image Binary Data

    Some annotations add images to a document. The content of such images is provided in an XML as well. To support this, a <documentAnnotations> element can have a child element <stampImages> that can include an arbitrary number of <stampImage> elements, each having two required elements:

    Name Type Description
    imageStampId string ID of an image that will be used by annotations to reference to it.
    base64format string Base64-encoded binary image data; this attribute uses the same format as HTML inline image does.

    Example

    &lt;documentAnnotations&gt;
        &lt;pages&gt;
            &lt;page id="1" pageWidth="612" pageHeight="792"&gt;
                &lt;annotation drawType="imagestamp"
                    imageStampId="sample-stamp-id-1"
                    x_percent="0.043" y_percent="0.028"
                    height_percent="0.093" width_percent="0.128" /&gt;
            &lt;/page&gt;
        &lt;/pages&gt;
        &lt;stampImages&gt;
            &lt;stampImage imageStampId="sample-stamp-id-1"
                        base64format="data: image/png;base64,iVBORw0K...kJggg=="/&gt;
        &lt;/stampImages&gt;
    &lt;/documentAnnotations&gt;
    
    

    Custom Type Definitions

    Color - in all attributes below “color” type means the attribute’s value can either be a “transparent” keyword, meaning no color at all should be applied for that piece of a redaction, or an integer value that represents a 24-bit RGB value of a desired color. This type does not support HTML hex color codes, such as “#F0F8FF” or HTML color names such as “AliceBlue”.

    Draw Type Descriptions

    arrow

    Draws a line with a triangle-shaped head. Same set of attributes, the size of an arrowhead is hard-coded and it also has the same color as the line itself. An arrowhead is drawn at the END side of the line (see dragDirection property of the line drawType).

    circle_filled

    Draws an ellipse that fits into a bounding rectangle. Uses the same attributes as rectangle_filled.

    circle_trans

    Draws an ellipse that fits into a bounding rectangle. Uses the same attributes as rectangle_filled.

    eSignDate

    Legacy synonym for text_redact annotation. _NOTE: Coordinate calculations may be slightly different from text_redact annotation._

    eSignEmail

    Legacy synonym for text_redact annotation. _NOTE: Coordinate calculations may be slightly different from text_redact annotation._

    eSignESignId

    Legacy synonym for text_redact annotation. _NOTE: Coordinate calculations may be slightly different from text_redact annotation._

    eSignInitials

    Legacy synonym for text_redact annotation. _NOTE: Coordinate calculations may be slightly different from text_redact annotation._

    eSignName

    Legacy synonym for text_redact annotation. _NOTE: Coordinate calculations may be slightly different from text_redact annotation._

    eSignSignature

    Draws a text entry that is composed of two text strings and a date string. Allows adding current date to the document. Its content is positioned at the bottom of the bounding rectangle. Note that eSignWidth and eSignHeight attributes override width_percent and height_percent attributes of the boundary rectangle.

    Annotation text is built from following parts, in that order:

    1. eSignIdLabel attribute value;
    2. uuid attribute value;
    3. eSignDate attribute value. If this attribute is not specified, current date is used.

    Text attributes are controlled by an esign-specific set of attributes (see below), unlike other text annotations that are controlled by HTML-like markup.

    Supported attributes:

    Name Type Required / Default Description
    eSignWidth int 280 Overrides the boundary rectangle width.
    eSignHeight int 10 Overrides the boundary rectangle height.
    eSignIdLabel string eSign ID: Signature label (first part of the signature annotation text).
    eSignUuid string <empty string> Signature uuid (second part of the signature annotation text).
    eSignDate string <current date> Signature date (third part of the signature annotation text).
    eSignFontFace string Tahoma Font name to use; same limitations apply as when using a font name for a text_redact.
    eSignFontSize int 8 Font size to use.

    See also: Common Attributes

    eSignText

    Legacy synonym for text_redact annotation. _NOTE: coordinate calculations may be slightly different from text_redact annotation._

    eSignTitle

    Legacy synonym for text_redact annotation. _NOTE: coordinate calculations may be slightly different from text_redact annotation._

    freehand

    Draws an arbitrary SVG path using a limited subset of commands - only absolute versions of L, C and M SVG path commands are supported at the moment. The drawn path is scaled to fit a boundary rectangle using the parameters listed below, while keeping the aspect ratio.

    The path data itself is expected to be provided in a CDATA child element of the freehand <annotation> element. The path data is expected to be a set of commands, each followed by a comma-separated list of coordinate arguments; see the following example:

      &lt;annotation drawType="freehand" align="left" lineWidth="4"
        pathWidth="381.6459330143541" pathHeight="178.622009569378"
        x_percent="0.057416267942583726" y_percent="0.10598811077279977"
        height_percent="0.22553284036537627" width_percent="0.6236044657097289"&gt;
    
        &lt;![CDATA[M0,50.75L0.08,50.51C0.16,50.26,0.32,49.77,0.97,48.31]]&gt;
    
      &lt;/annotation&gt;
    
    

    Supported attributes:

    Name Type Required / Default Description
    pathWidth float Yes Absolute width of the provided path. This is expected to correlate with the coordinates provided within the path data. This parameter is used to define the scaling factor when scaling the path to fit into the boundary rectangle.
    pathHeight float Yes Absolute height of the provided path. This is expected to correlate with the coordinates provided within the path data. This parameter is used to define the scaling factor when scaling the path to fit into the boundary rectangle.
    lineWidth int 1 Width of the path line, in pixels
    lineColor color black Color of the path line
    align string No Path line horizontal alignment in the annotation boundary rectangle.
    Can have one of the following self-explanatory values:
    • right
    • left

    Missing the parameter or setting it to any other value will result to default behavior (center aligned path line).

    See also: Common Attributes

    highlightText

    This is an utility annotation that effectively allows to draw several rectangles using the same color, border and opacity settings as a rectangle_filled, while having a set of rectangles defined in <line-rectangles> child elements exactly as it is done in text_hyperlink_annotation.

    imagestamp

    A legacy synonym of an imagestamp_redact.

    imagestamp_redact

    Draws an image over a given area. The image is scaled to fit its content into a boundary rectangle, keeping aspect ratio.

    Supported attributes:

    Name Type Required / Default Description
    imageStampId string Yes id of an image to use (see Image Binary Data above).

    See also: Common Attributes

    line

    Draws a line from one corner of a bounding rectangle to another. A line has a drag direction (see the attributes list); the following rules apply to a drag direction:

    • if it starts with “t”, then the line is directed “to the top”, meaning it goes from (Y + height) to (Y) in terms of vertical direction; otherwise it goes “to the bottom”;
    • if it ends with “r” then the line goes “to the right”, meaning it goes from (X) to (X + width); otherwise, it goes “to the left”.

    So, for instance, dragDirection “tl” means that a line will be drawn from a bottom-right to the top-left corner of a bounding rectangle.

    Supported attributes:

    Name Type Required / Default Description
    lineWidth int 1 width of the line, in pixels
    lineColor color black color of the line
    dragDirection string No Defines the direction of the line.
    Defines the placement of the arrowhead when used for an arrow.

    See also: Common Attributes

    polyline

    Draws a polyline. Annotation node of this type should contain coordinates of polyline points in its inner text, formatted as shown in example below:

      &lt;annotation drawType="polyline"&gt;
       &lt;![CDATA[[{"x":166.4,"y":95.1},{"x":262.07,"y":169.8},{"x":184.4,"y":199.1}]]]&gt;
      &lt;/annotation&gt;
    
    

    NOTES:

    • Polyline coordinates are specified in points
    • Boundary rectangle attributes are ignored for this annotation.

    Supported attributes:

    Name Type Required / Default Description
    lineColor color black Color of the line.
    lineWidth int 1 Width of the line, in pixels.

    See also: Common Attributes

    rectangle_filled

    Draws a rectangle, either filled or transparent.

    Supported attributes:

    Name Type Required / Default Description
    lineColor color 0 Rectangle border color.
    fillColor color 0 Rectangle fill color.
    lineWidth integer 0 Width of border in pixels. alpha integer 255 Alpha component that is added to fill and line colors. The default value is 255 for 100% opacity.
    opacity integer 255 Synonym of alpha attribute name.

    See also: Common Attributes

    rectangle_filled_redact

    Redacts a part of the document.

    NOTE: This is the only annotation that not only adds new content to a page but updates and removes some of the page's existing content, by doing what is called a “deep redaction”.

    When a drawType="rectangle_filled_redact" is applied to a page, the following happens:

    1. All text characters that are fully or partially covered by the area of the redaction get removed from the resulting document;
    2. Images that have some parts of them covered under a redaction area get their content filled with black (this is always black, no matter the fillColor attribute) in the intersection area, effectively destroying any security-sensitive image data under the covered area; NOTE: this feature is currently not supported for 1-bit JPEG 2000 images;
    3. A rectangle of the given color gets drawn above the full extend of the redaction area; black by default.
    4. Optionally, a text entry can be drawn over the redaction rectangle (usually explains the reason for the content redaction).

    Supported attributes:

    Name Type Required / Default Description
    lineWidth int 1 A width of a bounding rectangle border.
    lineColor color black Border color of a drawn rectangle.
    fillColor color black Fill color of a drawn rectangle.
    meta string No A text to draw over a rectangle.
    fontColor color white A color of a meta text font; if no “meta” is set, this parameter does not affect anything.

    See also: Common Attributes

    rectangle_trans

    Same behavior as rectangle_filled.

    rectangle_trans_redact

    This is effectively a rectangle_filled with different default values: default alpha is set to 25% opaque and default fill color is set to yellow (#FFFF00).

    signature_path

    Same behavior as freehand.

    signature_text

    Same behavior as text_redact, but without text wrapping, and with text centering vertically.

    stamp

    Adds rounded rectangle with centered text in it. Text is drawn exactly as for text_redact annotation with same attributes set, with the only exception that “stampSize” markup attribute is used for the font size instead of “size” attribute.

    Supported markup attributes:

    Name Type Required / Default Description
    stampSize 20 number Font size in pixels.

    See also: text_redact
    See also: Common Attributes

    stamp_redact

    A legacy synonym for a stamp.

    strikethrough

    This draw type applies a strikethrough annotation to the text that is specified inside selectedText property. Annotation that uses strikethrough property should contain <line-rectangles> and <rectangles> subelements, which define position and length of the strikethrough line.

      &lt;documentAnnotations&gt;
          &lt;pages&gt;
              &lt;page id=&quot;1&quot; pageWidth=&quot;612&quot; pageHeight=&quot;792&quot;&gt;
                  &lt;annotation nodeId=&quot;B4C6BF9B-C220-44B9-577C-8F4ADB7EED17&quot;
                  lineColor=&quot;0&quot; interactionMode=&quot;0&quot; stampSize=&quot;122&quot;
                  opacity=&quot;255&quot; x=&quot;163.01&quot; y=&quot;167.48&quot;
                  height=&quot;18.47999999999999&quot; width=&quot;38.94&quot;
                  drawType=&quot;strikethrough&quot; startIndex=&quot;70&quot;
                  selectedText=&quot;True&quot; textLength=&quot;4&quot;
                  highlightGroupID=&quot;13_1488462726580_8836&quot; isHighlight=&quot;y&quot;
                  lineWidth=&quot;2&quot; dragDirection=&quot;br&quot; meta=&quot;&quot;
                  label=&quot;&quot; saveDate=&quot;Thurs Mar 2 2017&quot;
                  saveTime=&quot;13:52:12 GMT+0000&quot; uuid=&quot;&quot; formUser=&quot;&quot;
                  created=&quot;Thurs Mar 2 13:52:6 GMT+0000 2017&quot; modified=&quot;Thurs Mar 2 13:52:6 GMT+0000 2017&quot;&gt;
                      &lt;line-rectangles&gt;
                          &lt;rectangle x=&quot;163.01&quot; y=&quot;167.48&quot; height=&quot;18.47999999999999&quot; width=&quot;38.94&quot;/&gt;
                      &lt;/line-rectangles&gt;
                      &lt;![CDATA[]]&gt;
                  &lt;/annotation&gt;
              &lt;/page&gt;
              &lt;page id=&quot;2&quot; pageWidth=&quot;612&quot; pageHeight=&quot;792&quot;/&gt;
          &lt;/pages&gt;
          &lt;highlights /&gt;
      &lt;/documentAnnotations&gt;
    
    

    Supported attributes:

    Name Type Required / Default Description
    lineWidth integer 2 Strikethrough line thickness in pixels.

    text

    Adds text with border. This acts exactly as applying both rectangle_trans and text_redact annotations with the attributes set that includes the attributes of both abovementioned draw types.

    text_hyperlink_annotation

    Adds hyperlink to the document.

    Supported attributes:

    Name Type Required / Default Description
    href yes string HTTP URL.
    lineColor 0 color Base color for hyperlink highlighting. If it is set to 0 or transparent, then default value will be used, which is blue color.
    fillColor 0 color Reserved, should be set to 0.

    See also: Common Attributes

    Annotation node of this type should contain <line-rectangles> and <rectangles> subelements, which define hyperlink area. The area, containing of several rectangles, would be highlighted and clickable. Each rectangle is defined by its top left corner coordinates, width and height as shown in this example:

      &lt;annotation ... &gt;
        ...
        &lt;line-rectangles&gt;
          &lt;rectangle x="226.8" y="225.7" height="11.3" width="315.5"/&gt;
          &lt;rectangle x="72" y="238.4" height="11.3" width="183.4"/&gt;
        &lt;/line-rectangles&gt;
      &lt;/annotation&gt;
    
    

    text_input_signature (reserved for internal use)

    Reserved for internal use and not currently supported by the Redaction API.

    text_redact

    This draw type adds a text entry to a document.

    There are no specific XML attributes (besides the usual bounding rectangle) for this draw type. For legacy reasons, parametrization of the text attributes (font, color, positioning and wrapping) are set in an html-like piece of markup in a CDATA child element of the <annotation>, like this:

    &lt;annotation x_percent="0.044" y_percent="0.052" height_percent="0.072" width_percent="0.21" drawType="text_redact"&gt;
        &lt;![CDATA[&lt;TEXTFORMAT&gt;&lt;P ALIGN="left" &gt;&lt;FONT FACE="Arial" SIZE= "12" COLOR="#000000"&gt;Sample Text Redaction
    With two lines&lt;/FONT&gt;&lt;/P&gt;&lt;/TEXTFORMAT&gt;]]&gt;
    &lt;/annotation&gt;
    
    

    Supported HTML-like font markup attributes:

    Name Type Required / Default Description
    ALIGN string No Controls the horizontal alignment of a text entry within the bounding rectangle area.
    Can have one of the following self-explanatory values:
    • RIGHT
    • MIDDLE or CENTER (synonyms)
    Setting ALIGN to any other value will result to default behavior (left aligned text).
    FACE string Arial Name of the font to use. For purposes of this annotation, the following font names can be used:
    • a font that is available to the OS;
    • a font that resides in a OS-specific fonts folder;
    • a font that resides in a specified fonts folder of a product (usually ./modules/fonts).
    SIZE float 20 Font size to use.
    COLOR string #000000 A usual HTML hex representation of an RGB color of a font to use:
    • This attribute uses a HTML-like hex color notation unlike the -color attributes of other annotations;
    • HTML color names are NOT supported;
    • You can NOT control the opacity of a text entry, it is always 100% opaque and will remain as such even when used as part of a semi-opaque complex annotation like text.

    text_selection_redaction (reserved for internal use)

    Reserved for internal use and not currently supported by Redaction API.