Word Macros vs. Velocity Templates for Formatting Fixes

Published Date: July 3, 2026
Audience: Everyone
Products and Versions Covered:

Jama Connect® version(s)
- Cloud/CVC
- Self-hosted

Summary

An Office Template's formatting does not always fully meet requirements on its own. Common problems include oversized images, tables wider than the page, unwanted rich text in the table of contents, inconsistent fonts, and empty paragraphs. A Word VBA macro can quickly fix these common issues. For more complete control over formatting, a Velocity template offers greater flexibility.

Resolution

Option A: Word VBA Macro

An Office Template macro that fixes common issues is available on GitHub: VBA_Word-Basic_Export

The macro runs automatically when you open an export from Jama, provided you enable macros after opening the document. It performs the following:

Resizes all images to fit on a single page
Resizes all tables to no wider than the page
Fixes unwanted Rich Text appearing in the Table of Contents
Adjusts all text to Arial font, regardless of what Jama specifies
Removes all empty paragraphs

Option B: Velocity Template

For an example of what Velocity can produce, see attached FormattedDocumentExample.docx, generated directly from Jama with no post-processing beyond updating fields and saving as .docx.

A Velocity template can handle:

Two-column format
Placing content in tables
Table formatting
Image resizing
Text reformatting
Headers and footers
Table/figure captions and references
Converting links between Jama items into Word cross-references

Comparing the two approaches

	Word Macro	Velocity Template
Pros	Quick to add to existing Office Templates easily customized per customer	Complete flexibility in document formatting Runs very fast All code is run on the Jama server
Cons	Requires users to enable macros — a security risk some IT organizations block entirely Can take a long time (up to an hour) for the macro to run on long documents Word appears to freeze while running The macro has not been developed with the most robust error handling, so unexpected issues maybe expose users to cryptic error messages	Long development time Only a few people are experienced in development

Word Macro

Velocity Template

Pros

Quick to add to existing Office Templates
easily customized per customer

Complete flexibility in document formatting
Runs very fast
All code is run on the Jama server

Cons

Requires users to enable macros — a security risk some IT organizations block entirely
Can take a long time (up to an hour) for the macro to run on long documents
Word appears to freeze while running
The macro has not been developed with the most robust error handling, so unexpected issues maybe expose users to cryptic error messages

Long development time
Only a few people are experienced in development

Additional Resources (for all external articles)

Feedback:
We welcome your input! Please sign in to leave any comments, suggestions, or ideas for improvement below.

Related to

FormattedDocumentExample.docx500 KB