Ctrl+K

Introduction to Drawing Endpoints

Introduction to Drawing Endpoints#

Workiva’s Drawings endpoints allow customers to interact with content in drawing containers such as floating content in a document section or presentation slide. This guide answers the following questions:

  • How do I retrieve drawing content from a document section?

  • How do I retrieve drawing content from a presentation slide or slide layout?

  • What are some common concepts to consider when working with drawings?

Example Use Cases#

How do I retrieve drawing content from a document section?#

The section’s drawingId is needed to retrieve the drawing content in a section. If a section contains drawing content, the drawingId can be found on the drawingBody.drawing property of the Section returned from a GET section or GET sections request. The drawingBody property will not be set on a section if a section does not have any drawing content.

Once you have the drawingId a GET drawing elements request can be made to retrieve the section’s drawing elements.

Note

Markup content is not currently supported.

How do I retrieve drawing content from a presentation slide or slide layout?#

The drawingId for a slide can be found on the slideBody.drawing property of a Slide returned from a GET slide or GET slides request.

The drawingId for a slide layout can be found on the slideLayoutBody.drawing property of a SlideLayout returned from a GET slide layout or GET slide layouts request.

Once you have the drawingId a GET drawing elements request can be made to retrieve the drawing elements of the slide or slide layout.

Common Concepts#

Drawing Element#

Drawing content is organized into a DrawingElementResult. All types of floating content in a document section or presentation slide are contained in a DrawingElement with a type property describing the type of floating content. Drawing elements types include lines, text boxes, shapes, tables, images, and charts.

All drawing elements have id, position, dimensions, and margins properties in addition to properties specific to their type, such as shape or embedded content information. All dimension, margin, and position measurements are in points.

Rich text in a drawing element can be found on the paragraphs property and is represented by a ParagraphsListResult similar to the rich text of a document section or rich text table cell. All Shape drawing elements include a paragraphs property for rich text.

Some drawing elements contain references to other content such as a TableDrawingElement, ImageDrawingElement, or ChartDrawingElement. In this case a request to the content endpoint associated with the embedded content, such as GET image or GET table, is needed to retrieve the drawing elements image or table information.

Drawing Position#

The position of a drawing element is represented by the DrawingRelativePosition, and consists of x and y coordinates from the top-left corner of the relative type’s relativity point. The x position is the horizontal offset, in points, from the left of the point. The y position is the vertical offset, in points, from the top of the point where positive numbers correspond to below the top edge.

Note

The position for Line drawing elements can be found on the head and tail properties.

Design Page Relative#

The DesignPageRelative drawing relative type corresponds to elements in document sections where design sections are enabled and the element’s positioning is fixed on the page. The relativity point for this relative type is the top-left corner of the section containing the element.

Paragraph Relative#

The ParagraphRelative drawing relative type corresponds to elements in document sections where design sections are not enabled, or the element’s positioning is not fixed on the page. The relativity point for this relative type is the start of a paragraph. In addition to x and y coordinates, this relative type includes a paragraphIndex corresponding to the element’s relative paragraph.

Slide Relative#

The SlideRelative drawing relative type corresponds to elements in a presentation slide or slide layout. The relativity point for this relative type is the top-left corner of the slide containing the element.