Managing Diagrams from Third-Party Editors (Draw.io / Visio)

Published Date: November 19, 2024
Validated: Yes
Audience: Everyone

Products and Versions Covered:

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

Summary

Diagrams created in third-party tools (e.g., Draw.io or Microsoft Visio) can be integrated into Jama Connect rich-text fields. However, workflows that attempt to import or convert diagrams directly into the Jama Connect diagram editor are not supported.

Jama Connect provides supported methods for storing, viewing, and maintaining diagrams. External conversion workflows (such as Draw.io imports using mxGraphModel) may fail or produce inconsistent results and are not supported by Jama Support.

This article outlines:

• Supported diagram management approaches
• Best practices for rendering and formatting
• Known limitations and how to mitigate them

Diagram Management Approaches in Jama Connect®

Resolution

Supported Approaches

1. Jama Connect Native Diagram Editor

• Open an item with a rich-text field
• Launch the diagram editor
• Create or edit your diagram
• Save the diagram and item

Result:
Diagrams are editable and versioned directly within Jama Connect.

2. Static Image + Link to Source (Recommended)

• Store the source diagram in a DMS or RCS
• Copy and paste the diagram as an image into a rich-text field
• Insert a URL linking to the source file (preferably version-specific)
• Save the item

To update:

• Open the source file
• Make updates in the external tool
• Replace the image in Jama Connect
• Update the link if needed

Result:
Maintains traceability while ensuring consistent rendering.

3. Attach Source Diagram Files

• Upload diagram files using the Attachments widget
• (Optional) Add a link in a rich-text field
• Save the item

To update:

• Locate the attachment
• Click Edit
• Upload a new version

Result:
Provides version control and centralized storage.

4. Draw.io / External Editor Conversion (Not Supported)

Attempting to convert diagrams from Draw.io into the Jama Connect diagram editor is not officially supported.

• Relies on the mxGraphModel format compatibility
• May fail or change without notice
• Jama Support cannot troubleshoot this workflow

Best Practice:
Use Draw.io (or similar tools) to create diagrams, then insert them as static images in Jama Connect.

Known Limitations

• Fonts may not persist when diagrams are saved from the native editor to rich-text fields
• Text may overflow or shift after saving
• Diagram sizing may change unexpectedly
• External conversions (e.g., Draw.io imports) are unreliable

Rendering & Formatting Best Practices

Jama Connect Diagram Editor

Text Overflow

Issue:
Text may extend outside of the shape boundaries after saving the diagram.

Recommendation:

• Reduce the font size by one or two points
• Use Ctrl + A to select all elements
• Use the Text tab to adjust font size consistently

Diagram Sizing

Issue:
After saving and closing the diagram editor, the diagram may appear too small in the rich-text field.

Recommendation:

• Reopen the diagram editor
• Keep the default zoom level (do not adjust zoom)
• Select Save and Close again

Image Quality (Visio)

Issue:
Images may appear low resolution when inserted into Jama Connect.

Recommendation:

• Export from Visio as PNG
• Select Printer Resolution
• Resize to ~1000px width

Third-Party Editor Settings

(Applies to Draw.io, Visio, Lucidchart, and similar tools)

Adaptive Colors

Issue:
Theme-based or adaptive colors may render incorrectly (often as black or white).

Recommendation:

• Avoid adaptive or theme-based colors
• Use explicit color values:
  • Black: #000000
  • White: #FFFFFF
• In Draw.io, change from User-defined to Automatic or fixed values

• Remove adaptive settings (e.g., Ctrl + Shift + 6)

Default Colors

Issue:
Using “Default” color settings can result in inconsistent rendering.

Recommendation:

• Do not use “Default” color settings
• Explicitly define:
  • Fill color
  • Line color
• Use standard hex values (e.g., #000000 or #FFFFFF)

Quick Reference: Common Issues & Fixes

Creating Higher-Resolution Images from Visio

If your image appears low quality:

1. In Visio, select Save As
2. Choose PNG
3. Select Printer Resolution
4. Upload into Jama Connect
5. Resize to ~1000px width

Result:
Improved clarity and readability.

Additional Resources

• Success Programs
• Success Catalog
• Datasheets
• Request a Solution Offering or Training from the Success Catalog

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