Document Generator MS Word Tags

A "tag" refers to an expression that the Document Generator can replace in a document template using JSON data.

Data

The JSON data can be stored in Object Storage or specified inline in a Request.

Example - Stored in Object Storage

  "data": {    
    "source": "OBJECT_STORAGE",
    "namespace": "my_namespace",
    "bucketName": "my_bucket",
    "objectName": "my_folder/names.json"
  }

Example - Specified inline in data.content

  "data": {
    "source": "INLINE",
    "content": [{"name":"John"},{"name":"Monica"}]
  }

Basic Tag

Syntax: {basic}

Used to inject text or numbers.

Examples


Tag	Data	Result
`{basic}`	`{"basic":"Hello!"}`	Hello!
`{number}`	`{"number": 7}`	7

Formatting

{basic} tags can be formatted. See Number Formatting for more details.

Sample documents


MS Word Template	JSON Data	Output
Word-Basic.docx	Word-Basic.json	Word-Basic-output.docx

Vertical Loop Tag

Syntax: {#loop}...{/loop}

A {#loop} tag is used to produce copies of a section of text vertically.

List Example

Data

{
  "class_list": [
    {
      "name": "Sue",
      "student_id": 1
    },
    {
      "name": "Bob",
      "student_id": 2
    },
    {
      "name": "Jean",
      "student_id": 3
    }
  ]
}

Template

Class List
{#class_list}* {student_id}: {name}
{/class_list}

Result

Class List
* 1: Sue
* 2: Bob
* 3: Jean

Table Example

Data

{
  "class_list": [
    {
      "name": "Sue",
      "student_id": 1
    },
    {
      "name": "Bob",
      "student_id": 2
    },
    {
      "name": "Jean",
      "student_id": 3
    }
  ]
}

Template


Id	Name
`{#class_list}{student_id}`	`{name}{/class_list}`

Result


Id	Name
1	Sue
2	Bob
3	Jean

Sample documents


MS Word Template	JSON Data	Output
Word-VLoop.docx	Word-VLoop.json	Word-VLoop-output.docx

Vertical Array Operations

Filter

The filter operation takes three arguments:

The property to filter on
The comparison to perform
The value to compare against

Currently, filtering is only supported on numeric types.

To use a filter, you must specify a new list, called {#filtered}...{/filtered} inside of the parent array doing the filtering.

Example

Data

{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}

Template

{#products|filter:price:>=:2}


Category	Name	Price
`{#filtered}{category}`	`{name}`	`{price}{/filtered}`

{/products|filter:price:>=:2}

Result


Category	Name	Price
Clothing	Shirt	3
Accessory	Hat	2

Sort

The sort operation takes two arguments:

The name of the property to use for sorting
asc or desc to sort the list in ascending or descending order.

To use a sort, you must specify a new list, called {#sorted}...{/sorted} inside of the parent array being sorted.

Example

Data

{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}

Template

{#products|sort:price:desc}


Category	Name	Price
`{#sorted}{category}`	`{name}`	`{price}{/sorted}`

{/products|sort:price:desc}

Result


Category	Name	Price
Clothing	Shirt	3
Accessory	Hat	2
Accessory	Belt	1

Distinct

The distinct operation takes a single argument:

The name of the property to select distinct values of.

Example

Data

{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}

Template

Categories:
{#products|distinct:category}

* {category}
  {/products|distinct:category}

Result

Categories:

* Accessory
* Clothing

Break

The break operator groups items together based on a shared property. It takes up to two arguments:

The name of the property to group items on.
asc or desc to sort the properties in ascending or descending order. This is optional, and defaults to the natural order.

To use a break, you must specify a new list, called {#break}...{/break} inside of the parent array being broken into groups.

Example

In this example note that the "Belt" and "Hat" items shared a category ("Accessory"), but they are not grouped in the array ("Belt" is the first item in the array and "Hat" is the last item).

Once the break operator has been applied, the items are grouped together in the output.

Data

{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}

Template

{#products|break:category}
{#break}* Category:{category}, Product:{name}
{/break}
{/products|break:category}

Result

* Category:Accessory, Product:Belt
* Category:Accessory, Product:Hat
* Category:Clothing, Product:Shirt

Group

Splits an array into subarrays of the given size. A single argument is required:

An integer specifying the group size.

To use a group, you must specify a new list, called {#group}...{/group} inside of the parent array being broken into groups.

If the array does not split perfectly into groups, the last group will be of smaller size. For example, if you have an array of 5 items, and you use group:2 on it, then two groups of two items and one group of one item will be created.

Example

Data

{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}

Template

{#products|group:2}Items
{#group}* {name}
{/group}
{/products|group:2}

Result

Items
* Belt
* Shirt
Items
* Hat

Sample documents


MS Word Template	JSON Data	Output
Word-VLoop-Arrays.docx	Word-VLoop-Arrays.json	Word-VLoop-Arrays-output.docx

Horizontal Loop Tag

Syntax: {:loop}...{/loop}

A {:loop} tag is used to produce copies of a section of text horizontally.

Table Example

Data

{
  "weekdays": [
    {
      "name": "Monday"
    },
    {
      "name": "Tuesday"
    },
    {
      "name": "Wednesday"
    },
    {
      "name": "Thursday"
    },
    {
      "name": "Friday"
    }
  ]
}

Template


Days	`{:weekdays}{name}{/weekdays}`

Result


Days	Monday	Tuesday	Wednesday	Thursday	Friday

Sample documents


MS Word Template	JSON Data	Output
Word-HLoop.docx	Word-HLoop.json	Word-HLoop-output.docx

Aggregators

Sum

The Sum Aggregator is used to calculate the sum of an array.

Example

Data

{
  "items": [
    {
      "name": "ball",
      "price": 1
    },
    {
      "name": "stick",
      "price": 2
    },
    {
      "name": "cup",
      "price": 3
    }
  ]
}

Template

Total Price: {items|sum:price}

Result

Total Price: 6

Average

The Average Aggregator is used to calculate the average of an array.

Example

Data

{
  "items": [
    {
      "name": "ball",
      "price": 1
    },
    {
      "name": "stick",
      "price": 2
    },
    {
      "name": "cup",
      "price": 3
    }
  ]
}

Template

Average Price: {items|avg:price}

Result

Average Price: 2

Max

The Max Aggregator is used to find the maximum value of an array.

Example

Data

{
  "items": [
    {
      "name": "ball",
      "price": 1
    },
    {
      "name": "stick",
      "price": 2
    },
    {
      "name": "cup",
      "price": 3
    }
  ]
}

Template

Max Price: {items|max:price}

Result

Max Price: 3

Min

The Min Aggregator is used to find the minimum value of an array.

Example

Data

{
  "items": [
    {
      "name": "ball",
      "price": 1
    },
    {
      "name": "stick",
      "price": 2
    },
    {
      "name": "cup",
      "price": 3
    }
  ]
}

Template

Minimum Price: {items|min:price}

Result

Minimum Price: 1

Sample documents


MS Word Template	JSON Data	Output
Word-Aggregators.docx	Word-Aggregators.json	Word-Aggregators-output.docx

Conditional Tags

# Tag

Syntax: {#<dataRef>}...{/<dataRef>}, where <dataRef> is a reference to a non-array property in your JSON data.

A conditional tag is used to hide a section of the document if a JSON property has the boolean value false, empty string (""), empty array ([]), null, or missing. If the JSON property has any other value, the section will not be hidden.

If the JSON property has an array value, this is a loop tag that will duplicate the section for each iteration of the loop. See Vertical Loop Tag.

Example

Data

{
  "address": "123 Main street",
  "nullValue": null,
  "falseValue": false,
  "empty_string": ""
}

Template

Displayed
1. {#address}Address: {address}{/address}

Hidden
1. {#missing_value} Condition is missing in JSON: {address}{/missing_value}
2. {#nullValue}Condition is null: {address}{/nullValue}
3. {#falseValue}Condition is Boolean false: {address}{/falseValue}
4. {#empty_string}Condition is an empty string: {address}{/empty_string}

End of document

Result

Displayed
1. Address: 123 Main street

Hidden
1.
2.
3.
4.

End of document

Sample documents


MS Word Template	JSON Data	Output
Word-Conditionals.docx	Word-Conditionals.json	Word-Conditionals-output.docx

Image Tag

Syntax: {%image}

An {%image} tag is used to inject an image into a document. Images can be provided from an OCI Object Storage Bucket, or from a URL. Images must be provided as an object, for example:

{
  "my_image": {
    "source": "OBJECT_STORAGE",
    "objectName": "image.png",
    "namespace": "object_storage_namespace",
    "bucketName": "my_bucket_name",
    "mediaType": "image/png"
  }
}

General

The specific schema for each source type is described below. Additionally, the following properties may be (optionally) included in the image object to control formatting of the image:

width: A string of digits, followed by unit of measure. E.G. 200px. Sets the width of the image.
height: A string of digits, followed by unit of measure. E.G. 200px. Sets the height of the image.
alt_text: A string. This will be set as the alternative text of the image.

Supported units of measure:

Document Generator supports the following units of measure for images:

px (pixels)
in (inches)
cm (centimeters)
% (percentage)

Default size of inserted images:

Smaller images: If an image is smaller than the page size, the original size is preserved.
Larger images: If an image is larger than the page size, it is resized to fit within the page width and height. The aspect ratio of the image is maintained.

Image scaling:

If only one image dimension is provided, the Document Generator will calculate a scaled value for the missing dimension in order to preserve aspect ratio. For instance:

If you provide a width, but no height, a scaled height will be calculated based on the image's native dimensions and the provided width.
If you provide a height, but no width, a scaled width will be calculated based on the image's native dimensions and the provided height.

Supported Formats

Document Generator supports the following image formats:

Schemas

OCI Object Storage

source: must be set to OBJECT_STORAGE
objectName: The path and name of the file
namespace: The namespace of your object storage bucket
bucketName: The name of the bucket that contains the file
mediaType: The Media Type (MIME) of the image

Example

Data

{
  "my_image": {
    "source": "OBJECT_STORAGE",
    "objectName": "image.png",
    "namespace": "object_storage_namespace",
    "bucketName": "my_bucket_name",
    "mediaType": "image/png",
    "width": "400px",
    "height": "200px"
  }
}

Template

{%my_image}

Result

URL

source: must be set to URL
url: the image URL in string format

Note: to use images from the Internet, Document Generator needs outbound access to the Internet. For example, if Document Generator is running in a private subnet in OCI, you could set up a NAT Gateway to allow Document Generator to connect to the Internet.

Example

Data

{
  "my_image": {
    "source": "URL",
    "url": "https://www.oracle.com/.../.jpg"
  }
}

Template

{%my_image}

Result

Data URL

Document Generator also supports the ability to pass images inside of Data URLs. The image must be Base64 encoded.

source: must be set to URL
url: the image URL in string format

Example

Data

{
  "my_image": {
    "source": "URL",
    "url": "data:image/png;base64,iVBORw0KG...go"
  }
}

Template

{%my_image}

Result

Sample documents


MS Word Template	JSON Data	Output
Word-Images.docx	Word-Images.json	Word-Images-output.docx

Page Break and Column Break Tag

Syntax: {?pagebreak} and {?columnbreak}

{?my_value} resolves a value from your data and inserts a:

Page break when the JSON value is a boolean true or a string equal to one of : pagebreak, page, true
Column break when the JSON value is a string equal to one of : columnbreak, column

Note that {?true} also inserts a page break.

Sample documents


MS Word Template	JSON Data	Output
Word-Breaks.docx	Word-Breaks.json	Word-Breaks-output.docx

Hyperlink Tag

Syntax: {*hyperlink}

A {*hyperlink} tag is used to insert a clickable hyperlink (including email addresses) into a document.

A hyperlink must be provided as an object with the following properties:

url: a URL in string format
url_text (optional): a string to be displayed instead of the URL

Example

Data

{
  "link": {
    "url": "https://www.oracle.com/",
    "url_text": "Click me!"
  }
}

Template

Follow the link: {*link}

Result

Follow the link: Click me!

Sample documents


MS Word Template	JSON Data	Output
Word-Hyperlinks.docx	Word-Hyperlinks.json	Word-Hyperlinks-output.docx

Number Formatting

If a value being supplied to a {basic} tag is a number, Document Generator supports the ability to format it.

A formatter is specified as follows: {input_number|format:[format]:[separators]:[currency_symbol]} where:

[format] is a supported number format
[separators] (optional) is a 2 character string. The first character indicates the decimal separator, the second character indicates the comma separator
[currency_symbol] (optional) the currency symbol to apply if L is present in [format]

Number formats must be specified in one of the following Oracle Number Formats:

FML999G999G999G999G990D00
FML999G999G999G999G990
999G999G999G999G990D00
999G999G999G999G990D0000
999G999G999G999G999G999G990
999G999G999G999G990D00MI
S999G999G999G999G990D00
999G999G999G999G990D00S
S999G999G999G999G990D00
999G999G999G999G990D00PR
FML999G999G999G999G990PR
999G999G999G999G990D00PR

Examples

The following table shows examples of these formats, given a number:


Template	unit_price: 1234.5	unit_price: -1234.5
`{unit_price\|format:"FML999G999G999G999G990D00":"<>":"$"}`	$1>234<50	-$1>234<50
`{unit_price\|format:"999G999G999G999G990D00":",."}`	1.234,50	-1.234,50
`{unit_price\|format:"999G999G999G999G990D00":", "}`	1 234,50	-1 234,50
`{unit_price\|format:"999G999G999G999G999G999G990"}`	1,234	-1,234
`{unit_price\|format:"999G999G999G999G990D00MI"}`	1,234.50	1,234.50-
`{unit_price\|format:"S999G999G999G999G990D00"}`	+1,234.50	-1,234.50
`{unit_price\|format:"999G999G999G999G990D00PR"}`	1,234.50	<1,234.50>
`{unit_price\|format:"FML999G999G999G999G990PR"}`	$1,234	<$1,234>

Date Formatting

If a value being supplied to a {basic} tag is an ISO 8601 date-time, Document Generator supports the ability to format it.

Time Zone considerations:

Input: When the time zone is not specified in the input date-time, UTC is used.
Output: When the time zone is not specified in the output date, the input time zone is used.

A formatter is specified as follows: {input_date|format_date:[format]:[time_zone]} where:

[format] is a supported date-time format
[time_zone] (optional) is a character string representing a time zone, such as America/Los_Angeles, UTC or +09:30.

Date-time output formats must be specified as a Java DateTime Formats.

Examples

The following table shows examples of these formats, given a date with a time zone:


Template	input_date: 2023-12-31T23:01:22-04:00
`{input_date\|format_date:"dd-MM-yy HH:mm:ss"}`	31-12-23 23:01:22
`{input_date\|format_date:dd/MM/yyyy}`	31/12/2023
`{input_date\|format_date:"MMM dd, yyyy HH:mm:ss"}`	Dec 31, 2023 23:01:22
`{input_date\|format_date:"yyyy-MM-dd HH:mm:ss":"America/Los_Angeles"}`	2023-12-31 19:01:22
`{input_date\|format_date:"yyyy-MM-dd HH:mm:ss":"UTC"}`	2024-01-01 03:01:22
`{input_date\|format_date:"yyyy-MM-dd HH:mm:ss":"Z"}`	2024-01-01 03:01:22
`{input_date\|format_date:"yyyy-MM-dd HH:mm:ss":"+09:30"}`	2024-01-01 12:31:22

The following table shows examples of these formats, given a date without a time zone:


Template	input_date: 2023-12-31T23:01:22
`{input_date\|format_date:"dd-MM-yy HH:mm:ss"}`	31-12-23 23:01:22
`{input_date\|format_date:dd/MM/yyyy}`	31/12/2023
`{input_date\|format_date:"MMM dd, yyyy HH:mm:ss"}`	Dec 31, 2023 23:01:22
`{input_date\|format_date:"yyyy-MM-dd HH:mm:ss":"America/Los_Angeles"}`	2023-12-31 15:01:22
`{input_date\|format_date:"yyyy-MM-dd HH:mm:ss":"UTC"}`	2023-12-31 23:01:22
`{input_date\|format_date:"yyyy-MM-dd HH:mm:ss":"Z"}`	2023-12-31 23:01:22
`{input_date\|format_date:"yyyy-MM-dd HH:mm:ss":"+09:30"}`	2024-01-01 08:31:22

Tag - Advanced Examples

Loop in Loop

In this example, we have 2 levels of loops. One for the movies and another for the actors.


MS Word Template	JSON Data	Output
Word-LoopInLoop.docx	Word-LoopInLoop.json	Word-LoopInLoop-output.docx

Aggregation and Formatting combination

In this example, the Total of the Invoice uses both Aggregation (sum) and Number Formatting.


MS Word Template	JSON Data	Output
Word-AggregationAndFormat.docx	Word-AggregationAndFormat.json	Word-AggregationAndFormat-output.docx

Oracle Cloud Infrastructure Documentation

Document Generator MS Word Tags

Data

Tags

Basic Tag

Examples

Formatting

Sample documents

Vertical Loop Tag

List Example

Data

Template

Result

Table Example

Data

Template

Result

Sample documents

Vertical Array Operations

Filter

Example

Data

Template

Result

Sort

Example

Data

Template

Result

Distinct

Example

Data

Template

Result

Break

Example

Data

Template

Result

Group

Example

Data

Template

Result

Sample documents

Horizontal Loop Tag

Table Example

Data

Template

Result

Sample documents

Aggregators

Sum

Example

Data

Template

Result

Average

Example

Data

Template

Result

Max

Example

Data

Template

Result

Min

Example

Data

Template

Result

Sample documents

Conditional Tags

# Tag

Example

Data

Template

Result

Sample documents