Document Management

• Version - A progress marker in the history of a document. Versions are immutable and capture the complete scope of a workspace at a particular point in time for future reuse or to revert a set of changes.
• Workspace - An active modeling/design space within a document.
• Branch - A branch is a named fork in the Version Manager graph of a document. Branches fork at a version, end with a workspace, and can have zero to N sequentially stored versions on the branch. The active branch is the branch of the document in which the currently open version or workspace is located.
• History entry - A record of a change made to a document workspace at a particular point in time. You can compare history entries and restore the document to a particular history entry (point in time) through the context menu in the Versions and history panel.
• In progress - The default release state for unreleased workspaces and versions. Objects in progress are either fully editable (in workspaces) or have editable metadata (in versions).
• Pending - The state of a Release candidate (and its revisionable objects) while awaiting approval by one or more approvers; indicated by this icon in the Version and history graph .
• Rejected - The state of a Release candidate (and its revisionable objects) that one or more approvers chose to reject; indicated by this icon in the Version and history graph .
• Released - The state of a Release candidate (and its revisionable objects) that was either successfully approved by one or more approvers or was immediately released by its creator, indicated by this icon in the Version and history graph. This icon also appears beside any released parts(in the Parts lists of a Part Studio) when viewing a released version of the document .
• Observer - Any member of a company who needs to be informed of the status of a release, but whose approval is not required in the release workflow. Any number of observers (or none) can be included on a Release candidate. An observer must have view permission on the document in order to observe the Release candidate.
• Approver - A company member whose approval is required in the release workflow. An approver has the ability to Approve or Reject a Release candidate. An approver must have permission to edit the document in order to approve or reject a Release candidate.
• Revisionable object - Any part, Assembly, Drawing, Variable Studio, or other file type in an Onshape document can be revisioned and released in Onshape.
• Release candidate - A user-selected group of revisionable objects that moves through the release workflow together. A Release candidate may contain a single part or an entire product including parts, Assemblies, Drawings, Variable Studios, and other files.
• Not revision-managed objects - Objects that may need to be included in a Release for reference purposes but whose revisions do not need to be tracked.

To learn more about how document history and versions work in Onshape, you can follow the self-paced course here: Document History and Versions (Onshape account required).

Onshape documents contain all of your project data and all of your work is automatically recorded. When working in a document, you work in an active workspace. When you create an Onshape document, one version and one workspace are automatically created for you (Start version and Main workspace). The Main workspace is also empty until you begin modeling.

The icon in the image above is the Document menu. The bold name is the Document name and the lighter name is the Workspace name.

Beneath the Document toolbar is the Document panel, which is vertically aligned along the left edge of the window. This panel provides access to the document's Versions and History.

The Main workspace and Start version are automatically created for you. These can be renamed.

A version is the state of an entire document at a particular point in time. The geometric data (and the accompanying properties like Part names, etc.) of that version is unchangeable. You have the ability to, however, change the properties of a version (more on this later). You may create many versions of a document. You may also branch your work at a version through the context menu command Branch to create a new workspace:

The features shown in the image above include (from top to bottom):

• Create Release icon , which opens a dialog from which you can create a Release candidate
• Create version icon , which allows you to create a version from the currently open workspace
• Compare history entries icon , which allows you to select two entries to compare
• The currently open workspace, highlighted in dark blue (in this case a branch, B1)
• Versions, including V1, V2, release asmb, re-release of part
• Version containing obsoletions, Rel-01
• Version that was automatically created through an Update all (references) through the Reference manager, V2

To create a version behind the scenes and still work in the same workspace, use the Create version icon in the Document panel (next to the document name).

This creates a version (visible in the Versions and history panel) without moving you away from the current workspace. The default naming convention is Vx: V for version, and x for the incremented number, starting from 1. You can always rename the versions.

The top arrow in the image above points to V2, the second version saved through .
The bottom arrow in the image above points to V1, the first version saved through .

Otherwise, open the Manage versions and history panel ( ) and create versions from the current workspace (using the Create version icon ).

Managing the workflow around versions and workspaces is performed through the Versions and history panel, accessed by clicking .

Onshape automatically records the state of each tab (Part Studio, Assemblies, etc) at each persisted change made to all tabs for every workspace by every user. This history of modifications is listed in the panel. At any time you are able to click Restore (in the context menu) to restore the branch/workspace to a particular point in its change history, click Return to <branch-name> to return to the currently active branch at its current point in history, and click a history entry to visualize the design at that point.

This graph displays all versions, workspaces, and releases of a document, in tree form. The graph is color-coded by branch. Every branch ends with a workspace, which are depicted as open dots. Versions are depicted as solid dots and are View only. Releases are depicted as triangles (solid for released, open for pending, and solid with a dot for obsoleted).

To simplify the view of a version graph, you can collapse the view to just the branch in which the currently active workspace resides by clicking Active branch at the top of the Versions and history panel.

The description of the record in the History list is Tab-name::Action:Feature-name. In addition, you have the ability to:

• Hover over an entry in the History list to see who made the modification, and when.
• Click after hovering to visualize the document at that history point (including the feature listed).
• Compare two history entries of the document.

Onshape keeps a history of all the changes made to every document by every user. This enables you to view those changes in one list in the document history, and also to restore a document to a specific point in history at any time.

When restoring, the workspace you are in is the one being restored. If you wish to restore to another workspace, open that workspace first.

Listing changes

To see all the changes made by every user who has worked on the document, since the creation of the document, click the Versions and history icon in the Document panel. Look for the Show changes entries and click the arrow to display the changes:

Every action is automatically stored and listed and serves as a complete audit trail. Changes are recorded for every action taken on the document since it was created, regardless of user or tab. When a list of changes exceeds more than 25 entries, the first 25 are shown. Click Show more to show more entries.

Restoring to a point in history

At any time, you are able to select a moment in the document's history to restore to. Remember that the Restore command is available only within a workspace. You are not able to restore a version, since versions are immutable. You are able to, of course, restore a workspace and then create a version of the restored workspace.

To restore:

1. Click to open the Versions and history panel.
2. Click the > arrow next to Changes in the list.
3. Right-click the change entry and select Restore to, to restore the workspace to that moment in the document's history.

   

4. To view the document at that moment in time before deciding whether to restore or not, click the entry.
   1. If you wish to restore after viewing the change, click the Restore to link to the right of the Versions and history panel:

   

Restoring is different from undo because you are able to restore all changes made to the document up to that point in the history, by any user on any tab. Undo, by contrast, reverts just the changes you made on the current tab. Right-click on the Undo icon to see a short list of changes you have made and select one to undo to that point without having to click the Undo button several times.

You can create and edit properties for parts, Part Studios, Assemblies, and foreign data in order to support your preferred design processes.

Properties are defined and edited through the Properties dialogs found on the context menus:

• Parts - In a Part Studio, from the context menu on the part listed in the Feature list; in the Versions and history panel, in the menu of a version or workspace
• Part Studios and Assemblies - Through the context menu on the tab; in the Versions and history panel, in the menu of a version or workspace
• Foreign data files - Through the context menu on the tab; in the Versions and history panel, in the menu of a version or workspace
• Releases - Through the context menu on the release in the Versions and history panel.