Toolbar with Update references icon highlighted

Onshape allows you to insert parts and assemblies from any document into any other document. We refer to this as linking documents since referencing a part or assembly that resides in one document from another document (or within different versions of the same document) creates a sort of virtual link between the two documents (or two versions of the same document).

Parts and assemblies inserted into other documents (or from versions of the same document) may be continually worked on in their source document or workspace and thus become out-of-date in the workspaces into which they were inserted.

How do you keep track of which objects are out-of-date and which to update without digging into each linked document? Onshape identifies the references for you with a series of icons indicating not only which objects reference another document or version, but also which objects have newer versions or revisions available. The out-of-date states are shown at all levels, for example: a sub-assembly is marked out-of-date if any of its children are out-of-date.

Knowing which objects can be updated gives you the confidence to perform an Update all references command Update references icon to update versions all the way through subassemblies up to the top-level assembly if you wish, or to perform individual or manual group updates, depending on your needs.

Using the Update all references command updates all references within the assembly, recursively, with the click of a single button to their newer versions. When you have a top-level assembly that contains multiple references to parts and subassemblies in other documents or in versions of the same document, you can update all references with this one command.

What if you want to update almost all references, but not exactly all of them? You can pin references to keep them from being updated automatically with the Update all command. See Pinning references to exclude from update, below.

How will you know when a reference is out-of-date, that is, when a newer version or revision of the referenced part or assembly is available? The icon indicating that a newer referenced part or assembly exists exhibits a blue background. For example:

  • linked document iconThis icon indicates that the part or subassembly is referencing a version from either the same document or another document and is up-to-date.
  • New version of linked document available icon When a newer version of the referenced part or subassembly is available, the icon exhibits a blue background like this. Consider any icon with a blue background to indicate that a newer version of the referenced object is available.

More specifically, the blue background appears when there are edits in a newer version of the same branch, and in the specific document tab of the referenced part or subassembly. References to tabs that do not have edits in a newer version do not have the blue linked icon even if there is a newer version without any changes.

Updating individual, or groups of, objectsCopy link

You can, of course, still click on the icon and select to update a single object or a group of objects. Click on each object to select those you want to update, then either right-click to access the context menu and select Update linked document or click one of the icons to open the Reference manager and initiate the update process. See Using the Reference manager below for more information.

An important scenario to note is that you can update to newer versions of parts or subassemblies from any top-level assembly. However, to update a part or subassembly to a newer revision requires that you navigate to the part or subassembly and update at that point first. Then you can update from the top-level assembly to pull the change through.

Pinning references to exclude from Update allCopy link

Sometimes you may want to disable the ability to update an object through the Update all button. To safeguard an object from being updated when the Update all button is clicked, you can pin the reference:

  1. Select the object in the Assembly Instances list.
  2. Right-click the icon and select Pin reference:

    Selecing Pin reference from the Instance context menu

  3. The icon gains a small thumbtack image:

    The thumbtack icon to the right of the instance signifying it is pinned

For references that exhibit a blue background (indicating a newer version exists), the new, pinned icon replaces the blue background with a circle. For example:

Instance has a new referenced version availale icon

Reference icon indicating a newer version exists

Linked instance has a newer version available on its branch and is pinned icon

Pinned reference icon indicating a newer version exists

Using Update allCopy link

If you want to update all references to their associated newer versions: click the Update all button in the toolbar:

Update all references icon

The Update all button performs a recursive update. That is, when a part or assembly inside of a top-level assembly has a newer version available, you can use the Update to latest tab of the Reference manager to pull that update through to the top-level assembly, automatically creating versions as needed in order to do so.

For example:

In the Instances list in BOARD_ASSEMBLY below, you can see by the icon on the TRUCK_ASSEMBLY, that a subassembly within it is out-of-date. The expanded list shows that the WHEEL_ASSEMBLY contains a subassembly BALL_BEARING that contains a part BEARING_OUTER that is out-of-date:

Instances list showing examples of the update reference icons next to instances

To view update options, click the icon next to TRUCK_ASSEMBLY to open the Reference manager:

Viewing update options for the instance in the Reference manager dialog

The Update to latest tab of the Reference manager shows that many of the subassemblies contain parts or subassemblies that are out-of-date. Note that these objects do not list a newer version under them in the list, only 'new version'; this means a new version must be created in the linked document in order for the object to be updated.


Notice that BEARING_OUTER.x_t was left out of the list above. This is because this part actually has a newer version available already (V2).

When updating a reference that has newer versions available on different branches, you are prompted to choose the workspace from which to pull the update. Selecting the workspace updates the instance to the latest version on that branch:

Choosing a workspace to which the instance is updated

When Update all is clicked, the following happens:

  1. New versions are created for the following:

    • BALL_BEARING<1>-2
    • BALL_BEARING<2>-2
  2. Those objects are updated to the newly created versions.
  3. Since BEARING_OUTER.x_t already has a newer version available, no new version is created, and this object is updated to V2.

Using the Reference managerCopy link

The Reference manager is where you decide which version to update your linked references to. You can elect to perform a blanket "Update to latest" command (explained above) or to use a more "Selective update" and choose the versions to update to:

  1. To open the Reference manager, click on a version or triangle icon next to a top-level instance in the assembly.

    Alternatively, you can click the Update all button to open the Reference manager for the assembly.

    Reference manager dialog

  2. However you open the Reference manager, make sure the Selective update filter is selected.

    See above for instructions for Using Update all.

    Reference manager dialog, showing that a newer version is available for the instance, and with the Update selected button

  3. Check the box beside the object you wish to update.

    If necessary, use the Version icon to open the Version and history graph for that object so you can select the specific version you wish to use for the update. You can update to a previous version if you wish.

    Reference manager dialog showing the Release candidate version

  4. Click Update selected.

Updating pinned objects

  1. If the icon has a blue background, you can update it from the top-level assembly. (If the icon does not have a blue background, first navigate to the subassembly of the object and perform these steps there.)
  2. Click the icon next to the pinned object.

    Regardless of whether the pinned object is out-of-date or up-to-date, the Reference manager opens to the Selective update filter.

    This method works only for top-level assemblies. To update pinned children inside of subassemblies, navigate to the subassembly itself and update there.

  3. Select the version or revision to which you want to update and click Update selected.
    • Use the Pinned icon Pinned icon to filter the list to show only pinned instances.
    • Use the Revision icon Revision icon to filter the list to show only instances that have a newer revision available.
    • Use the Version graph icon Version and history graph icon to display the Version and history graph for the object in order to select the specific version to update to.
  4. Click Update selected.

TipsCopy link

  • All versions are updated to the latest version when using update all, even those that are not out-of-date.
  • The Update to the latest tab in the Reference manager indicates if any document doesn’t have write permission. If there are any documents without write permission listed in the Reference manager, the Update button is disabled.