Escribal
Back to Docs

Text Doc

Images & shapes

This group of instructions adds and manages visual elements in a document: images (from a file or a web address), geometric shapes, text boxes, charts, and math equations. It also lets you adjust images already in the document — resize, crop, reposition, change how text wraps around them, set brightness and contrast, add a caption, or set alternative text for accessibility.

Prerequisite: before using any of these instructions, the workflow must already have a DOCX document created or opened (with Create text doc), which these instructions will act upon.

These concepts recur across several instructions in this group; they are explained here once.

  • Document: indicates which document in the workflow the instruction applies to. If left empty, the current document is used.

  • Dynamic values (@name): in any text field you can type @ followed by the name of a value saved earlier in the workflow, and it will be replaced by that value. For example, if you saved a file path in logoPath, you can type @logoPath in the Image file path field.

  • Two ways of locating things — Search text vs Image name:

    • The instructions that add an element (Insert Chart, Insert Image From File/Url, Insert Shape, Insert Text Box, Insert Math Equation) use a Search text field to decide where to place the new element: it is added to the first paragraph whose text contains that text. If Search text is left empty, the element is added at the end of the document.
    • The instructions that change an existing image (Resize Image, Crop Image, Set Alt Text, Set Brightness Contrast, Set Image Position, Set Text Wrapping, Add Image Caption) use an Image name field to decide which images to affect. Leaving it empty means all images; giving a name affects every image with that name.

  • Image names: every image has a name used to refer to it later. An image inserted from a file takes the file name without its extension; an image from a URL takes the Image name you give it. You can save that name with Save image name in and reuse it in the Image name field of the other instructions.

  • Case sensitive: for the instructions that place an element by Search text, this decides whether the match distinguishes upper- and lower-case. It is off by default (so Chapter also matches chapter).

  • Sizes, positions, and colors: widths, heights, and positions are given in centimeters (cm); some fields use percentages; colors are given as hex codes (for example FF0000 for red), with or without a leading #.

  • Saving a result: Insert Image From File and Insert Image From Url offer a Save image name in field that stores the inserted image’s name under a name you choose, so you can reuse it later. If left empty, nothing is saved.

  • “From variable” fields: the @name trick only works in text fields. So that a numeric field (such as Width (cm) or Brightness) can also take its value from a saved value, it has a companion (from variable) field:

    • If you leave it empty, the value typed in the normal field is used.
    • If you fill it in with the name of a saved value, the engine ignores the normal field and uses that variable’s value.

    This is mainly for chaining instructions (one instruction saves a value, the next one reads it). If you only work with fixed values, you can ignore these fields.

Add Image Caption .docx

Inserts a caption line (such as “Figure 1”) just below the paragraph that contains an image.

When to use it: to label a figure with an automatically numbered caption.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Image name Name of the images to caption; empty = every image in the document. Supports @name (empty) No
Prefix Label shown before the number (for example Figure). Supports @name Figure No
Caption text Optional description shown after the number; empty = just the label and number. Supports @name (empty) No

Important behavior: a caption is added below every matching image (below every image when Image name is empty); if there is no matching image, nothing happens. The caption uses the document’s “Caption” style and its number updates automatically, so captions stay in order even if you add more.

Crop Image .docx

Trims the edges of an image by a percentage, without changing the file.

When to use it: to hide unwanted borders or focus on part of a picture.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Image name Name of the images to crop; empty = all images. Supports @name (empty) No
Crop left (%) Percentage trimmed from the left edge (0–100) 0 No
Crop right (%) Percentage trimmed from the right edge (0–100) 0 No
Crop top (%) Percentage trimmed from the top edge (0–100) 0 No
Crop bottom (%) Percentage trimmed from the bottom edge (0–100) 0 No

Important behavior: applies to every matching image (all images when Image name is empty); if no image is found, nothing happens. Cropping hides part of the image — it does not resize the frame.

Delete Chart .docx

Removes a chart from the document by its name

When to use it: to rebuild a chart from scratch, or to drop one that no longer belongs in the document.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Chart name Name of the chart to remove. Supports @name (empty) Yes
Save count key Name to save how many were removed under (empty) No

Important behavior: the name is required; with it empty the instruction does nothing. Only charts are removed: an image or a shape with the same name is left alone.

Delete Image .docx

Removes an image from the document by its name

When to use it: to drop a picture that a later step replaces, or one that should not reach the final document.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Image name Name of the image to remove. Supports @name (empty) Yes
Save count key Name to save how many were removed under (empty) No

Important behavior: the name is required: unlike the instructions that change images, where an empty name means “all of them”, leaving it empty here does nothing — deleting every image in a document by leaving a field blank would be too easy. Only images are removed: a shape or a chart with the same name is left alone. If the run that held the image is left empty, it goes too, so no blank space is left behind.

Delete Shape .docx

Removes a shape from the document by its name

When to use it: to take out a shape added earlier that the final document should not show.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Shape name Name of the shape to remove. Supports @name (empty) Yes
Save count key Name to save how many were removed under (empty) No

Important behavior: the name is required; with it empty the instruction does nothing. Only shapes are removed: an image or a chart with the same name is left alone.

Insert Chart .docx

Inserts a bar, line, or pie chart built from a list of labels and values.

When to use it: to add a simple data chart directly from the workflow, without a spreadsheet.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Search text The chart is placed in the paragraph containing this text; empty = end of document. Supports @name (empty) No
Chart type bar, line, or pie bar No
Labels Comma-separated category names (for example Jan,Feb,Mar). Supports @name A,B,C No
Values Comma-separated numbers (for example 10,20,30). Supports @name 10,20,30 No
Width (cm) Chart width in centimeters 12 No
Height (cm) Chart height in centimeters 8 No
Case sensitive Whether the search-text match is case-sensitive No No
Height (from variable) Reads the height from a saved value (empty) No
Case sensitive (from variable) Reads the yes/no value from a saved value (empty) No
Width (from variable) Reads the width from a saved value (empty) No

Important behavior: labels and values are paired up to the shorter of the two lists; any extra entries are ignored. A value that is not a number counts as 0. An unrecognized chart type is treated as bar.

Insert Image From File .docx

Inserts a picture from a file on your computer.

When to use it: to add a logo, photo, or any local image to the document.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Image file path Full path to the image file. Supports @name (empty) Yes
Search text The image is placed in the paragraph containing this text; empty = end of document. Supports @name (empty) No
Width (cm) Image width in centimeters 6 No
Height (cm) Image height in centimeters 4 No
Case sensitive Whether the search-text match is case-sensitive No No
Height (from variable) Reads the height from a saved value (empty) No
Case sensitive (from variable) Reads the yes/no value from a saved value (empty) No
Width (from variable) Reads the width from a saved value (empty) No
Save image name in Name under which to save the inserted image’s name (empty) No

Important behavior: if the path is empty, nothing happens; if a path is given but the file does not exist, the instruction reports an error and the workflow stops. PNG, GIF, BMP, and TIFF files are recognized by their extension; any other extension is treated as JPEG. The image’s name (used by the other instructions) is the file name without its extension.

Insert Image From Url .docx

Downloads a picture from a web address and inserts it.

When to use it: to add an image hosted online without downloading it by hand first.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Image URL Web address of the image. Supports @name (empty) Yes
Image name Name given to the image, used to refer to it later. Supports @name RemoteImage No
Search text The image is placed in the paragraph containing this text; empty = end of document. Supports @name (empty) No
Width (cm) Image width in centimeters 6 No
Height (cm) Image height in centimeters 4 No
Case sensitive Whether the search-text match is case-sensitive No No
Height (from variable) Reads the height from a saved value (empty) No
Case sensitive (from variable) Reads the yes/no value from a saved value (empty) No
Width (from variable) Reads the width from a saved value (empty) No
Save image name in Name under which to save the inserted image’s name (empty) No

Important behavior: if the URL is empty, nothing happens; if a URL is given but the image cannot be downloaded, the instruction reports an error and the workflow stops.

Insert Math Equation .docx

Inserts a mathematical equation as a new paragraph.

When to use it: to add a formula to the document. This is an advanced instruction: it expects the equation already written in Office Math (OMML) format.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Equation (OMML) The equation in Office Math (OMML) format. Supports @name (empty) Yes
Search text The equation is placed after the paragraph containing this text; empty = end of document. Supports @name (empty) No
Case sensitive Whether the search-text match is case-sensitive No No
Case sensitive (from variable) Reads the yes/no value from a saved value (empty) No

Important behavior: if the equation field is empty, or the text is not valid Office Math markup, nothing happens.

Insert Shape .docx

Inserts a floating geometric shape filled with a color.

When to use it: to add a simple decorative or highlighting shape to the page.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Search text The shape is placed in the paragraph containing this text; empty = end of document. Supports @name (empty) No
Shape type Chosen from the shared shape list (see below); stored as rect, roundrect, ellipse, triangle, rightarrow, leftarrow, uparrow, downarrow, star, diamond, pentagon, hexagon or callout rect (Rectangle) No
Width (cm) Shape width in centimeters 5 No
Height (cm) Shape height in centimeters 3 No
Fill color Fill color as a hex code 4472C4 No
Case sensitive Whether the search-text match is case-sensitive No No
Height (from variable) Reads the height from a saved value (empty) No
Case sensitive (from variable) Reads the yes/no value from a saved value (empty) No
Width (from variable) Reads the width from a saved value (empty) No

Important behavior: Shape type is picked from the same list of 13 shapes as Insert Shape .xlsx and Insert Preset Shape .pptx — rectangle, rounded rectangle, ellipse, triangle, the four arrows (right, left, up, down), star, diamond, pentagon, hexagon and callout — so it cannot be typed freely and does not accept @name. The shape floats over the text rather than sitting inline.

Insert Text Box .docx

Inserts a floating box containing text.

When to use it: to place a caption, note, or callout that can sit anywhere on the page.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Content The text shown inside the box. Supports @name (empty) No
Search text The box is placed in the paragraph containing this text; empty = end of document. Supports @name (empty) No
Width (cm) Box width in centimeters 6 No
Height (cm) Box height in centimeters 3 No
Case sensitive Whether the search-text match is case-sensitive No No
Height (from variable) Reads the height from a saved value (empty) No
Case sensitive (from variable) Reads the yes/no value from a saved value (empty) No
Width (from variable) Reads the width from a saved value (empty) No

Important behavior: the text box floats over the text rather than sitting inline.

Resize Image .docx

Changes the size of one or more images already in the document.

When to use it: to make images bigger or smaller, either by exact size or by percentage.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Image name Only images with this name are resized; empty = all images. Supports @name (empty) No
Width (cm) New exact width in centimeters; 0 = do not set an exact width 0 No
Height (cm) New exact height in centimeters; 0 = do not set an exact height 0 No
Width (%) Scale the width to this percentage of its current width; 0 = ignored 0 No
Height (%) Scale the height to this percentage of its current height; 0 = ignored 0 No
Width (from variable) Reads the width from a saved value (empty) No
Height (from variable) Reads the height from a saved value (empty) No
Width % (from variable) Reads the width percentage from a saved value (empty) No
Height % (from variable) Reads the height percentage from a saved value (empty) No

Important behavior: for each dimension the exact size (cm) takes precedence; if it is 0, the percentage is used; if that is also 0, the dimension is left unchanged. If Image name is empty, every image is resized.

Set Alt Text .docx

Sets the alternative text (accessibility description) of images.

When to use it: to describe images for screen readers and improve accessibility.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Image name Only images with this name are changed; empty = all images. Supports @name (empty) No
Alt text The description assigned to the image(s). Supports @name (empty) No

Important behavior: if Image name is empty, the alt text is set on every image in the document.

Set Brightness Contrast .docx

Adjusts the brightness and contrast of an image.

When to use it: to lighten, darken, or sharpen the look of a picture.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Image name Name of the images to adjust; empty = all images. Supports @name (empty) No
Brightness From -100 to 100; 0 = no change 0 No
Contrast From -100 to 100; 0 = no change 0 No
Brightness (from variable) Reads the brightness from a saved value (empty) No
Contrast (from variable) Reads the contrast from a saved value (empty) No

Important behavior: applies to every matching image (all images when Image name is empty). If both values are 0, any previously applied brightness/contrast adjustment is removed.

Set Image Position .docx

Places a floating image at an exact position on the page.

When to use it: to pin an image to a specific spot, measured from the page edges.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Image name Name of the floating images to move; empty = all floating images. Supports @name (empty) No
Horizontal (cm) Distance from the left edge of the page 2 No
Vertical (cm) Distance from the top edge of the page 2 No
Horizontal (from variable) Reads the horizontal distance from a saved value (empty) No
Vertical (from variable) Reads the vertical distance from a saved value (empty) No

Important behavior: this only works on floating images. An image becomes floating when you apply Set Text Wrapping to it; inline images are not affected. Applies to every matching floating image (all floating images when Image name is empty).

Set Text Wrapping .docx

Turns an inline image into a floating one and sets how text flows around it.

When to use it: to let text wrap around an image instead of sitting on its own line.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Image name Name of the images to change; empty = all images. Supports @name (empty) No
Wrapping square, tight, through, topBottom, behind, or front. Supports @name square No

Important behavior: this converts inline images into floating ones so text can wrap around them, for every matching image (all images when Image name is empty). A Wrapping of inline does nothing. Only real pictures can be converted — charts and shapes cannot. behind places the image behind the text and front places it in front.

This documentation is the help of the application, and it comes underCreative Commons Attribution 4.0.