AutoCAD DWG files frequently reference other DWG files – title blocks, site plans, standard parts, shared assets. These external references (XREFs) normally break outside AutoCAD, so a drawing previewed alone renders incomplete.
AODocs resolves XREFs automatically: it matches the referenced files against the attachments of the document and of its related documents, then rebuilds the drawing so the Autodesk Viewer displays it complete. By configuring your shared assets once on a document class template, every new DWG document is linked to them automatically – no manual linking, no broken XREFs.
Notes:
– XREF management is available in libraries using Google Cloud or Azure storage (not Google Drive).
– It requires the Autodesk Viewer integration and CAD data extraction to be activated (feature flags enableAutodesk and enableAutodeskExtraction). They're activated on demand by AODocs – contact your AODocs sales representative.
This article explains how to:
Automatically generated table of contents
How XREF resolution works
1. Extraction – when a DWG file is uploaded, AODocs extracts the list of files it references and stores it with the attachment.
2. Matching – when the references are verified, each referenced file is matched by file name against the attachments of the document and of all its related documents.
3. Reconciliation – the drawing is rebuilt together with its matched references, and the Autodesk Viewer displays the complete drawing.
Note: Matching is based on the file name only (ignoring folder paths and capitalization). Keep the attachment names identical to the file names referenced in the DWG – renaming an asset attachment breaks the match.
Configure automatic XREF linking with templates
As a library administrator, you can make every new DWG document automatically linked to the documents that hold your shared assets.
Step 1: Create a relation between your classes
Configure a relation between the document class of your drawings and the class holding your shared asset files – for example, Drawings → Standard assets.
Step 2: Define default related documents on the template
1. Open your drawing document class and select the Templates tab. Learn more: Manage your document templates.
2. Edit the template and add the asset documents – the documents whose attachments are referenced by your drawings – as related items.
3. Save the template.
screen: The document class Templates tab with a template being edited, showing the shared asset documents added as related items.
Step 3: Create drawings from the template
Every document created from the template is automatically linked to the asset documents. Users can add more related documents on top of the defaults.
Notes:
– The default related documents apply to documents created from the template after you configure them. Existing documents aren't linked retroactively.
– If an asset document is deleted, or the relation is removed, it's silently skipped when documents are created. Review your templates when you reorganize your asset documents.
– The defaults follow the document class's copy configuration: the relations section – and each relation – must be allowed for copy.
Verify external references on a drawing
XREF verification is started manually by the user viewing the drawing:
1. Open the DWG attached file in the Autodesk Viewer.
2. Click Verify external references in the viewer toolbar (available for DWG files only).
screen: The Autodesk Viewer toolbar with the Verify external references button highlighted on a DWG file.
3. AODocs scans the document and its related documents for the referenced files:
- If the drawing has no external references, you're notified that everything is up to date.
- If all references are found, the drawing is rebuilt in the background: "Reconciling Xrefs in the background. Please refresh the page in a few moments to view the updated visualization."
- If some references are missing, a dialog lists the matched and missing files: "Add the missing file(s) to this document or a related document, then retry."
screen: The verification result dialog "Some Xrefs are missing", listing matched files with a green check and missing files with a red cross.
4. Refresh the page to display the complete drawing.
Note: The same verification also runs automatically before a DWG is converted to PDF, so exported PDFs include the referenced geometry.
Limitations
- References are matched by file name only. If two related documents hold different files with the same name, the first match is used.
- Files uploaded before CAD data extraction was activated have no extracted reference data. Upload a new version of the file to trigger the extraction.
- The resolution is a snapshot: after adding missing files, run Verify external references again.
- Nested references (an XREF that itself references other files) are resolved only as far as they're listed by the main drawing.
Troubleshooting
I don't see the Verify external references button. The button appears only on DWG files opened in the Autodesk Viewer, and requires the Autodesk integration to be activated on your tenant.
The dialog says some Xrefs are missing. The referenced files aren't attached to the document or any of its related documents. Add the missing files – with the exact same file names – to the document or a related document, then run the verification again.
The drawing is still incomplete after verification. The reconciliation runs in the background: wait a few moments and refresh the page. If it persists, check that the attachment names match the referenced file names exactly.
New documents aren't linked to the asset documents. The default related documents only apply to documents created from the template after the configuration. Also check that the relation still exists and that the class's copy configuration allows copying relations.