Markup Burner XML Specification

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:

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:

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:

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

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:

Example:

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

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 hardcoded 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:

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:

  <annotation drawType="freehand" lineWidth="4"
    pathWidth="381.6459330143541" pathHeight="178.622009569378"
    x_percent="0.057416267942583726" y_percent="0.10598811077279977"
    height_percent="0.22553284036537627" width_percent="0.6236044657097289">

    <![CDATA[M0,50.75L0.08,50.51C0.16,50.26,0.32,49.77,0.97,48.31]]>

  </annotation>

Supported attributes:

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:

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:

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:

  <annotation drawType="polyline">
   <![CDATA[[{"x":166.4,"y":95.1},{"x":262.07,"y":169.8},{"x":184.4,"y":199.1}]]]> 
  </annotation>

Note:

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

Supported attributes:

See also: Common Attributes

rectangle_filled

Draws a rectangle, either filled or transparent.

Supported attributes:

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 pages’ 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:

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 and horizontally.

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:

See also: text_redact
See also: Common Attributes

stamp_redact

A legacy synonym for a stamp.

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:

See also: Common Attributes

Annotation node of this type should contain <line-rectangles> and <rectangles> sub-elements, 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:

  <annotation ... > 
    ... 
    <line-rectangles>
      <rectangle x="226.8" y="225.7" height="11.3" width="315.5"/>
      <rectangle x="72" y="238.4" height="11.3" width="183.4"/>
    </line-rectangles>
  </annotation> 

text_input_signature (reserved for internal use)

Reserved for internal use, not supported by Redaction API at the moment.

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, parameterization of the text attributes (font, color, positioning and wrapping) is set in a html-like piece of markup in a CDATA child element of the <annotation>, that goes like this:

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

Supported HTML-like font markup attributes:

text_selection_redaction (reserved for internal use)

Reserved for internal use, not supported by Redaction API at the moment.