Custom annotation extensions vs out-of-the-box markup tools: collaboration and upgrade considerations

PLM Aras Innovator
, , , , , , , ,
1

Our engineering teams need enhanced annotation capabilities in the CAD viewer beyond the standard markup tools. Requirements include measurement annotations with automatic dimension calculations, custom annotation templates for common review comments, and integration with our change request system to automatically create ECRs from annotated issues.

We’re evaluating whether to develop custom annotation extensions or work within the constraints of Aras’s out-of-the-box markup functionality. Custom extensions would give us exactly the features engineers want, but I’m concerned about compatibility with future viewer updates and the maintenance burden.

Looking for perspectives on balancing feature richness against upgrade impact, particularly from teams who’ve navigated viewer version transitions with custom annotation tools. How much customization is too much when it comes to the CAD viewer?

system 2

Custom Annotation Extensions: Upgrade Risk Framework and Decision Architecture

The core tension here is viewer API surface stability vs. feature completeness. Aras’s CAD viewer (historically powered by Autodesk Platform Services / Forge Viewer, verify current viewer engine in your version) exposes a JavaScript API that can shift significantly between Innovator platform releases — custom extensions built against it are the most upgrade-sensitive customization category in the entire platform.

Pre-Upgrade Checks (Run Before Any Innovator Upgrade)

  • Identify your viewer engine version and the target version’s bundled viewer engine — these can diverge independently of Innovator version numbering
  • Audit all files under ../Innovator/Client/Solutions/PLM/javascript/ and any custom packages referencing Autodesk.Viewing, markupCore, or markupTools APIs
  • Check whether you’re using private/internal viewer APIs (prefixed with _ or undocumented in Autodesk Forge Viewer changelog) — these break silently
  • Validate your ECR integration hooks: if they call Aras Methods via aras.getMethods() or direct IOM calls from viewer context, confirm the IOM API contract hasn’t changed in the target release
  • Run the Aras Upgrade Comparison Tool (verify availability in your version) against your custom package manifest to flag schema conflicts
  • Back up the full vault, database, and code tree — not just the database

Recommended Approach: Layered Extension Architecture

Rather than choosing between full custom or pure OOB, structure customization in upgrade-resilience tiers:

  1. Tier 1 — Configuration only: Use OOB markup templates and annotation styles for standard review comments. Zero upgrade risk.
  2. Tier 2 — Supported extension points: Implement measurement annotations using the viewer’s documented MarkupTool extension API (verify API name in your viewer version). Wrap your code in a versioned Aras Package Definition with explicit dependency declarations.
  3. Tier 3 — ECR integration: Build this as a server-side Aras Method triggered by a relationship on the Markup ItemType, not as viewer-embedded JavaScript. This decouples the business logic from the viewer lifecycle entirely.
// Pattern: Isolate viewer API calls behind a version-abstraction wrapper
// Reduces breakage surface during viewer engine upgrades
const AnnotationBridge = {
  _viewerVersion: Autodesk.Viewing.VERSION,
  createMeasurement: function(viewer, params) {
    // Single point of change when API shifts
    return viewer.loadExtension('Autodesk.Measure', params);
  }
};

Upgrade Step Sequence (Source → Target Innovator Version)

  1. Deploy target version to isolated environment with production data clone
  2. Run Aras upgrade installer — do not apply custom packages yet
  3. Load baseline viewer in target; confirm OOB markup functions correctly
  4. Apply custom package via Aras Package Import utility; log all conflicts
  5. Test AnnotationBridge wrapper against new viewer API; update abstraction layer only
  6. Validate ECR Method trigger end-to-end (ItemType schema changes affect relationship queries)
  7. Regression test with representative CAD assemblies — viewer bugs surface with specific geometry complexity

Rollback Procedure

  • Restore database from pre-upgrade backup
  • Redeploy source version code tree (keep binaries versioned in source control)
  • Reimport last-known-good custom package from your package archive
  • Verify vault file references resolve correctly post-restore

The “Too Much” Threshold

You’ve crossed it when your custom code overrides viewer core files directly rather than extending via the extension API, or when ECR logic lives inside viewer JavaScript. The abstraction layer pattern above keeps you on the right side of that line. Teams that embed business logic in viewer extensions typically spend 3–5x more effort per upgrade than those using the server-side Method pattern.

This draft is based on general Aras Innovator knowledge. It has not been verified against your specific version and environment. Practitioners: verify the steps and share your experience below.

3

We built custom annotation extensions in Aras 11 and deeply regretted it when upgrading to 13. The viewer architecture changed significantly, and our custom JavaScript extensions broke completely. Took us two months to refactor everything to work with the new viewer API. Standard markup tools would have upgraded automatically.

4

Standard markup tools have improved significantly in recent Aras versions. Before investing in custom extensions, verify that OOB functionality doesn’t already meet your needs. We thought we needed custom annotations for measurements, but Aras 14’s enhanced markup includes dimension tools that satisfied 80% of our requirements. The remaining 20% we handled through workflow integration rather than viewer customization.

5

Maria, the dimension tools in 14.0 are helpful, but we need automatic annotation templates - engineers repeatedly add the same review comments and it’s tedious to recreate them manually each time. Does the standard viewer support annotation templates or saved markup sets that can be reused across different CAD files?

6

For the ECR integration requirement, don’t customize the viewer itself. Instead, build a server-side integration that extracts markup data from the standard annotation format and creates change requests. The viewer’s markup data is stored in a documented XML schema that you can parse without touching viewer code. This approach gives you the integration functionality while keeping the viewer completely standard.

7

Viewer customizations are the highest-risk category for upgrade compatibility. Aras updates the viewer technology stack more frequently than core PLM functionality, and each update can introduce breaking changes to custom extensions. We maintain a strict policy: customize viewer behavior only through documented APIs and extension points, never by modifying viewer core files or injecting custom JavaScript into the viewer frame.

8

The documented API approach sounds safer. Are there specific Aras viewer APIs for adding custom annotation types or templates? I want to understand what’s possible within the supported extension framework before deciding whether custom development is necessary.

9

Based on painful lessons learned, here’s my perspective on custom annotation extensions versus standard markup tools:

Out-of-the-Box Markup Tools Should Be Your Foundation Aras 14.0’s standard viewer includes comprehensive markup capabilities that handle most collaboration scenarios:

  • Text annotations with formatting options
  • Dimension measurements with automatic calculations
  • Geometric markup (arrows, clouds, rectangles, freehand)
  • Snapshot annotations capturing specific views
  • Markup persistence across CAD file revisions
  • Markup visibility controls and filtering
  • Export markup to PDF for offline review

These tools are optimized for performance, fully supported through upgrades, and integrate seamlessly with Aras workflows and change management.

Upgrade Impact of Custom Viewer Extensions Custom annotation extensions carry significant upgrade risk:

  • Viewer technology stack updates frequently (WebGL, JavaScript frameworks, rendering engines)
  • Custom JavaScript injected into viewer context breaks when viewer architecture changes
  • Viewer API changes between major versions often require extension refactoring
  • Custom markup formats may become incompatible with newer viewer versions
  • Testing custom extensions across viewer updates is time-consuming and error-prone

Our custom annotation extensions in Aras 11 broke completely during the 11 to 13 upgrade when Aras transitioned to a new viewer architecture. We spent two months rewriting extensions that standard markup would have handled automatically.

Safe Customization Patterns If you must extend annotation functionality, follow these safe patterns:

  1. Server-Side Markup Processing: Extract and process markup data on the server without modifying viewer code. The viewer stores annotations in documented XML format that you can parse, analyze, and integrate with other systems.

  2. Workflow Integration: Build custom workflows that react to markup events (annotation created, markup approved, review completed) rather than customizing the viewer itself.

  3. Documented Extension Points: Use only officially documented viewer APIs and extension mechanisms. Avoid direct DOM manipulation or injection of custom JavaScript into viewer frames.

  4. Markup Templates via Configuration: Create annotation templates as saved markup sets stored in Aras items. Users can load templates into standard viewer rather than requiring custom viewer code.

Addressing Your Specific Requirements:

Measurement Annotations: Aras 14.0’s OOB dimension tools provide automatic calculations. Test whether these meet your needs before custom development.

Annotation Templates: Implement templates as saved Markup items that users can load into the viewer. Create a library of common review comments stored as standard markup that can be applied to any CAD file. This avoids viewer customization entirely.

ECR Integration: Build server-side integration that monitors markup activity and creates change requests based on annotation content. Parse the standard markup XML format to extract issue descriptions, locations, and reviewer comments. This integration approach keeps the viewer completely standard while providing the workflow automation you need.

Practical Recommendation: Start with OOB markup tools and build integration logic around them. Create annotation templates as reusable Markup items, implement server-side processing for ECR creation, and use standard workflow to orchestrate the review process. Only consider custom viewer extensions if you have requirements that absolutely cannot be met through standard markup plus server-side integration.

The upgrade safety, long-term maintainability, and reduced testing burden of standard markup tools far outweigh the short-term appeal of custom annotation features. Every viewer customization is technical debt that compounds with each Aras upgrade.