Linking Documents

Consider a case where one Onshape document (UsingDoc) contains an assembly that instances a part that resides in another Onshape document (RefDoc). In Onshape, versions are always immutable, so anything defined in a version of RefDoc is stable and recoverable. Since linked document references are to versions, this means that every change in the history of UsingDoc is also stable and recoverable. And, as a result, versions created in UsingDoc are also stable and recoverable. This is a fundamental architectural advantage Onshape has relative to traditional file-based CAD.

Instead of changes to RefDoc propagating into UsingDoc with no recourse, you are informed when new versions are available and you choose whether to use them or not. If it becomes obvious that the new version causes a problem, you can use the document history to restore back to a prior working state.

A key aspect of linking documents is that all of Onshape’s document permissions work seamlessly. You decide when a document should change from Editable to View only to Reference only on a per user basis - and you are always able to change permissions whenever you want.

In an Assembly:

1. Click Insert to open the Insert dialog.
2. The default is to insert from the current workspace. To insert a part or assembly from another document, select Other documents.

   You can insert from another document only when that document has versions. If the selected document doesn’t have any versions, or you do not have edit permission (to create a version) Onshape displays a notification and allows you to version the document immediately:

   

   Click the link to open the Create version dialog for that document:

   

   Enter the appropriate and necessary information, click Create and return to the Insert dialog.

3. Select a part or assembly from the document.
4. Click the check to close the dialog.

If a newer version of the part or assembly becomes available in the source document, you are notified via the icon in the document into which you inserted the part or assembly. A blue background appears around the linked icon to indicate that a newer version is available.

Once a part is inserted from another document, you can open the document from which the part is linked, if needed, for editing the part or to obtain a closer inspection of the part:

1. Right-click on the part in the Instances or Features list and select Open linked document.
2. A new browser tab opens, with the linked document open to the version that was linked to and the Part Studio of the part you selected active.
3. Make whatever inspection you need, or edit the part, if desired.
4. If you edit the part, in the tab you'll see the blue icon that indicates another version of the part is available. Click that icon to open the Reference manager .

Errors you may encounter

If the linked document you are trying to open is in the Trash, you will get an error: Failed to load document for workspace. Cannot open a document in the trash. Restore the document from Trash.

If the document is permanently deleted, you will see the message: Failed to load document for version. Resource does not exist, or you do not have permission to access it.

If you do not have permission to edit the linked document, you will see this message: You cannot modify this feature because you cannot access the referenced document.

• While the case described here is for Linked Documents, you can reference parts and assemblies defined in different versions on the same document as well.
• Select a linked item in the Feature list, right-click and select Open linked document to open the linked document in a new tab in your browser window.
• To allow another user to link to your document, share the document with at least Read/Copy/Export permissions (or higher).
• You can export linked documents on the browser platform.
• If you then unshare the document (remove a user from the list in the Share dialog), the removed user is blocked only from updating to a newer version and creating links to that. Any links already used will still work.

Consider a case where one Onshape document (UsingDoc) contains an assembly that instances a part in another Onshape document (RefDoc). In Onshape, versions are always immutable, so anything defined in a version of RefDoc is stable and recoverable. Since Linked document references are to versions, this means that every change in the history of UsingDoc is also stable and recoverable. And, as a result, versions created in UsingDoc are also stable and recoverable. This is a fundamental architectural advantage Onshape has relative to traditional file-based CAD.

Instead of changes to RefDoc propagating into UsingDoc with no recourse, the user is informed when new versions are available and chooses whether to use them or not. If it becomes obvious that the new version causes a problem, you can use the document history to restore a working prior state.

A key aspect of linking documents is that all of Onshape’s document permissions work seamlessly. You decide when a document should change from Editable to View only to Reference only on a per user basis - and you always have the ability to change permissions whenever you want.

There are three ways in which you can link documents.

• Insert Parts and Assemblies

  In an Assembly, tap the Insert Part and Assemblies icon:

  

  Follow the steps in the Insert Parts and Assemblies topic to select a part or assembly to insert.

• Derive

  In a Part Studio, tap the Derived tool:

  

  Follow the steps in the Derived topic to select a part to insert.

• Add Custom Feature

  In a Part Studio, tap the Add Custom feature tool:

  

  Follow the steps in the Custom Feature topic to select a custom feature to add to the feature toolbar.

  Inserted parts or assemblies, derived parts, and custom features linked to from another document are indicated in the Instance list or the Feature list by a link icon. Tabs will also have a link icon to indicate that something in that tab is linked to another document.
  
  When a newer version of the document from which you inserted a part or assembly, derived a part, or added a custom feature is created, the link icon highlights in blue. This indicates that you are able to update your document to the newest version of the document to which it is linked.
  

When a reference document is updated, Onshape adds an updated link icon next to the part in the Instance list, feature in the Feature list, and also in the respective tab.

Tap the overflow menu next to an updated link icon (in the Feature list, Instance list, or on a tab) and select Update to access the Reference manager.

Reference manager

You have the ability to either update all of your references to their latest versions at once or select specific references to update.

Update to latest - to update all of your references to their latest versions:

1. Tap Update to latest.

   Available newer versions are listed.

2. Tap Update All.

Selective update - to chose specific references to update to their latest versions:

1. Tap Selective update.

   Available newer versions are listed, with checkboxes.

2. Tap to select one or more items from the list.
3. Tap Update Selected.

Updating linked documents

When a referenced document is updated, Onshape adds a linked icon next to the part in your document:

The gray link icon indicates a part referenced (linked) from another document. The white link icon with the blue background indicates that a part referenced from another document now has another version. This notification is also visible on the Assembly tab.

To update a linked document:

Where you see a white link icon with a blue background (either in the instance list or in the Assembly tab) tap the overflow menu or tap the tab.

Where you see a white link icon with a blue background (either in the instance list or in the assembly tab) tap the overflow menu.

Tap to select Update or Update link from the overflow menu.

• While the case described here is for Linked Documents, you are also able to reference parts and assemblies defined in different versions on the same document as well.
• Select a linked item in the Feature list, tap the overflow menu, and select Open linked document to open the linked document in a new tab in your document.
• To allow another user to link to your document, share the document with at least Read/Copy/Export permissions (or higher).
• If you then unshare the document (remove a user from the list in the Share dialog), the removed user is blocked only from updating to a newer version and creating links to that. Any links already used will still work.

Consider a case where one Onshape document (UsingDoc) contains an assembly that instances a part in another Onshape document (RefDoc). In Onshape, versions are always immutable, so anything defined in a version of RefDoc is stable and recoverable. Since Linked document references are to versions, this means that every change in the history of UsingDoc is also stable and recoverable. And, as a result, versions created in UsingDoc are also stable and recoverable. This is a fundamental architectural advantage Onshape has relative to traditional file-based CAD.

Instead of changes to RefDoc propagating into UsingDoc with no recourse, the user is informed when new versions are available and chooses whether to use them or not. If it becomes obvious that the new version causes a problem, you are able to use the document history to restore a working prior state.

A key aspect of linking documents is that all of Onshape’s document permissions work seamlessly. You decide when a document should change from Editable to View only to Reference only on a per user basis - and you are always able to change permissions whenever you want.

There are three ways in which you are able to link documents.

• Insert Parts and Assemblies

  In an Assembly, tap the Insert Part and Assemblies icon:

  

  Follow the steps in the Insert Parts and Assemblies topic to select a part or assembly to insert.

• Derive

  In a Part Studio, tap the Derived tool:

  

  Follow the steps in the Derived topic to select a part to insert.

• Add Custom Feature

  In a Part Studio, tap the Add Custom feature tool:

  

  Follow the steps in the Custom Feature topic to select a custom feature to add to the feature toolbar.

  Inserted parts or assemblies, derived parts, and custom features linked to from another document are indicated in the Instance list or the Feature list by a link icon. Tabs will also have a link icon to indicate that something in that tab is linked to another document.
  
  When a newer version of the document from which you inserted a part or assembly, derived a part, or added a custom feature is created, the link icon highlights in blue. This indicates that you are able to update your document to the newest version of the document to which it is linked.
  

Once a part is inserted from another document, you can open the document from which the part is linked, if needed, for editing the part or to obtain a closer inspection of the part:

1. Tap on the three dot menu next to the part in the Instances or Features list and select Open linked document.
2. A new browser tab opens, with the linked document open to the version that was linked to and the Part Studio of the part you selected active.
3. Make whatever inspection you need, or edit the part, if desired.
4. If you edit the part, in the tab you'll see the blue icon that indicates another version of the part is available. Click that icon to open the Reference manager.

Errors you may encounter

If the linked document you are trying to open is in the Trash, you will get an error: Failed to load document for workspace. Cannot open a document in the trash. Restore the document from Trash.

If the document is permanently deleted, you will see the message: Failed to load document for version. Resource does not exist, or you do not have permission to access it.

If you do not have permission to edit the linked document, you will see this message: You cannot modify this feature because you cannot access the referenced document.

When a reference document is updated, Onshape adds an updated link icon next to the part in the Instance list, feature in the Feature list, and also in the respective tab.

Tap the overflow menu next to an updated link icon (in the Feature list, Instance list, or on a tab) and select Update to access the Reference manager.

Reference manager

You have the ability to either update all of your references to their latest versions at once or select specific references to update.

Update to latest - to update all of your references to their latest versions:

1. Tap Update to latest.

   Available newer versions are listed.

2. Tap Update All.

Selective update - to chose specific references to update to their latest versions:

1. Tap Selective update.

   Available newer versions are listed, with checkboxes.

2. Tap to select one or more items from the list.
3. Tap Update Selected.

Updating linked documents

When a referenced document is updated, Onshape adds a linked icon next to the part in your document:

The gray link icon indicates a part referenced (linked) from another document. The white link icon with the blue background indicates that a part referenced from another document now has another version. This notification is also visible on the Assembly tab.

To update a linked document:

Where you see a white link icon with a blue background (either in the instance list or in the Assembly tab) tap the overflow menu or tap the tab.

Where you see a white link icon with a blue background (either in the instance list or in the assembly tab) tap the overflow menu.

Tap to select Update or Update link from the overflow menu.

• While the case described here is for Linked Documents, you are also able to reference parts and assemblies defined in different versions on the same document as well.
• Select a linked item in the Feature list, tap the overflow menu, and select Open linked document to open the linked document in a new tab in your document.
• To allow another user to link to your document, share the document with at least Read/Copy/Export permissions (or higher).
• You can export linked documents on the Android platform.
• If you then unshare the document (remove a user from the list in the Share dialog), the removed user is blocked only from updating to a newer version and creating links to that. Any links already used will still work.