Extensions

Onshape provides options for embedding commands in various menus, fly-out panels, and elements via extensions.

We can classify extensions into two high-level types. The first type embeds a UI from the application into the Onshape UI. The embedded UI is an HTTPS page displayed in an iFrame in the Onshape UI. The UI is served from the application, and can choose to make API calls to Onshape for additional information. This is exactly like the traditional tab-based applications in Onshape, except that such extensions exist at different UI locations.

The second type of extension embeds an action that calls a REST API exposed by the application from the Onshape UI (e.g., context menu actions and toolbar actions). These types of extensions rely on External OAuth information to authenticate and make a call where Onshape acts as a client, and the application acts as a server.

Creating an extension

1. For personal accounts, go to the developer portal: https://cad.onshape.com/appstore/dev-portal. For company, classroom, or enterprise accounts, go to your Enterprise Settings: Developer.
2. Click the OAuth applications section, then select your application.
3. Click the Extensions tab.
4. Click Add extension.
5. Fill out the form:
   • Name: Can be truncated in the UI if it is too long.
   • Description (optional): Does not appear in the Onshape UI, but could appear in the grant process.
   • Location: Where the extension exists in the Onshape UI. See Supported Locations and Contexts.
     • You can create only one element tab extension per application.
   • Context: Some locations work in the context of a selection, such as inside a Part Studio. See Supported Locations and Contexts.
   • Action URL: Locations that embed a UI use the action URL to define the address of the page to display. The action URL is used to specify the REST endpoint if the location is an action (context menu, toolbar item, action in dialog etc.) and the action type is GET or POST. If the location is an action and the action is Open in new window, the action URL is the URL to open in the new window. See Action URL parameters for a list of parameters that can be used in this field.
   • Action type: Applicable for locations that do not embed UIs. Supported action types are:
     • GET - This makes a GET API call using the action URL. Parameter replacement is done on the action URL.
     • POST - This makes a POST API call using the action URL and the action body as the post body. Parameter replacement is done on both the action URL and the action body.
     • Open in new window - This opens the action URL in a new browser window. Parameter replacement is done on the action URL.
   • Action body: Only applicable for POST action types. The action body is passed in a POST API call and must be in a valid JSON format.
   • Show response: This is only applicable if the action type is GET or POST. When selected, the UI waits for a response and shows the response in a dialog in the UI. The response must be in a valid JSON format.
   • Icon: The icon will be shown where the extension exists. This can be an icon in an Info panel, context menu action, toolbar button, action button in a dialog, or other supported locations.
6. Click OK.

See Hello World for a working example of creating a simple extension.

Action URL parameters

The action URL can be parameterized to pass information from Onshape to the application. The action URL replaces attributes in the format {$attribute} with the appropriate value. These attributes can be used to identify the selected entity and/or make calls back to Onshape via the API. The currently supported attributes are:

• {$documentId} - The Onshape ID for the current or selected document.
• {$workspaceOrVersion} - This will be either w or v for workspace or version respectively depending on current opened document state or selection.
• {$workspaceOrVersionId} - The Onshape ID for the current or selected workspace or version.
• {$microversionId} - The Onshape ID for the current or select document microversion.
• {$tabElementId} - The Onshape ID for the current tab.
• {$elementId} - The Onshape ID for the current or selected element.
  • Usually, tabElementId and elementId are the same. However, when creating an extension with the Selected instance context, tabElementId indicates the current tab (i.e., the target element), and elementId indicates the tab from which the instance/subassembly was inserted (i.e., the source element).
• {$partId} - The Onshape ID for the current or selected part.
• {$partNumber} - The Part number property for the current or selected part, assembly or drawing.
• {$revision} - The Revision property for the current or selected part, assembly or drawing.
• {$companyId} - The ID for the company that owns the document.
• {$mimeType} - The mime type if the current or selected element is a blob.
• {$featureId} - In case of feature selected in the Feature list in a Part Studio.
• {$nodeId} - In case of mate or mate feature selected in the Assembly list.
• {$occurrencePath} - In case of part instances, mates, mate connectors and sub assemblies.
• {$configuration} - In case of extensions inside the document, this attribute will be replaced by current element active configuration.
• {$sessionCompanyId} - The company ID for the signed-in user’s session.

The attributes can exist as path parameters or query parameters or attributes in the POST body. For example:

https://cad.onshape.com/api/partstudios/d/{$documentId}/{$workspaceOrVersion}/{$workspaceOrVersionId}/e/{$elementId}/stl?server=https://cad.onshape.com&companyId=cad&userId=5f1eba76c14a434817d9c588&locale=en-US

The attributes available for replacement differ by location and context selection.

The timeout for action_url of type GET or POST is 180 seconds.

Supported locations and contexts

Element context menu

This is the context menu for elements.

Supported contexts:

• Part Studio
• Assembly
• Drawing
• Blob element

Supported parameters for replacements:

• {$documentId}
• {$workspaceOrVersion}
• {$workspaceOrVersionId}
• {$workspaceId} DEPRECATED
• {$versionId} DEPRECATED
• {$elementId}
• {$partNumber}
• {$mimeType}
• {$configuration}

Default parameters as query string:

• server
• companyId - Default value is ‘cad’. If the document owner is company/enterprise, then the value is company/enterprise ID.
• userId
• locale
• clientId

This location supports action types.

Tree context menu

This is the context menu for the part tree, assembly tree and feature tree in part studios.

Supported contexts:

• Part
• Sub assembly
• Feature
• Mate
• Mate feature
• Instance

Supported parameters for replacement:

• {$documentId}
• {$workspaceOrVersion}
• {$workspaceOrVersionId}
• {$workspaceId} DEPRECATED
• {$versionId} DEPRECATED
• {$elementId}
• {$partId} (Part and Instance contexts only)
• {$partNumber}
• {$revision}
• {$featureId}
• {$nodeId}
• {$occurrencePath}
• {$configuration}

Default parameters as query string:

• server
• companyId - Default value is ‘cad’. If the document owner is company/enterprise, then the value is company/enterprise ID.
• userId
• locale
• clientId

This location supports action types.

Document list context menu

This the context menu available on items in the document list. This is normally documents but can be multiple types based on search results.

Supported contexts:

• Part
• Document
• Part Studio
• Assembly
• Drawing
• Blob element

Supported parameters for replacement:

• {$documentId}
• {$workspaceOrVersion}
• {$workspaceOrVersionId}
• {$workspaceId} DEPRECATED
• {$versionId} DEPRECATED
• {$elementId}
• {$partId} (Part context only)
• {$partNumber}
• {$revision}
• {$configuration}

Default parameters as query string:

• server
• companyId - Default value is ‘cad’. If the document owner is company/enterprise, then the value is company/enterprise ID.
• userId
• locale
• clientId

This location supports action types.

Document list info panel

This is the Info panel to the right in the document list. The document list normally contains documents, but can contain other entities as the result of a search.

Supported contexts:

• Part
• Document
• Part Studio
• Assembly
• Drawing
• Blob element

Supported parameters for replacement:

• {$documentId}
• {$workspaceOrVersion}
• {$workspaceOrVersionId}
• {$workspaceId} DEPRECATED
• {$versionId} DEPRECATED
• {$elementId}
• {$partId}

Default parameters as query string:

• server
• companyId - Default value is ‘cad’. If the document owner is company/enterprise, then the value is company/enterprise ID.
• userId
• locale
• clientId

This location does NOT support action types.

Element right panel

See also: Element right panel extensions

This is the panel inside a document. It currently houses the BOM, configurations, etc. Applications can use this extension location to add items in this panel.

Supported contexts:

• Part
• Document
• Part Studio
• Assembly
• Sub assembly
• Feature
• Mate
• Mate feature

Supported parameters for replacement:

• {$documentId}
• {$workspaceOrVersion}
• {$workspaceOrVersionId}
• {$workspaceId} DEPRECATED
• {$versionId} DEPRECATED
• {$elementId}
• {$partNumber}
• {$revision}
• {$featureId}
• {$nodeId}
• {$occurrencePath}
• {$configuration}

Default parameters as query string:

• server
• companyId - Default value is ‘cad’. If the document owner is company/enterprise, then the value is company/enterprise ID.
• userId
• locale
• clientId

This location does NOT support action types.

Element tab

This is the menu option for + menu -> Add application inside a document . After menu click, a new tab will be created with the action url associated with this extension.

Supported contexts:

• There are no supported contexts.

Supported parameters for replacement:

• Parameter replacement not supported.

Default parameters as query string:

• documentId
• workspaceId
• versionId
• elementId
• server
• companyId - Default value is ‘cad’. If the document owner is company/enterprise, then the value is company/enterprise ID.
• userId
• locale
• clientId

This location supports action types.

Part number generator

This extension helps partners to embed their own custom part number generation scheme in Onshape. Each application can have only one extension of this type. Once defined, these extensions are listed as one of the part numbering schemes in the release management configuration in Company settings.

In the above screen shot, ‘Part number generation scheme’ is the user-defined name of the extension.

Supported contexts:

• There are no supported contexts.

Supported parameters for replacement:

• Parameter replacement is not supported.

Default parameters as query string:

• No default query parameters

Action URL defined by the user is assumed to be a POST API. This API should consume a predefined request body as shown below. This definition may have additional attributes in future.

 {
  "id" : <partNumberId>,
  "documentId" : <documentId>,
  "elementId" : <elementId>,
  "workspaceId" : <workspaceId>,
  "elementType" : <elementType>,
  "partId" : <partId>,
  "companyId" : <companyId>, // Id of the company that owns the document, else the text “cad”
  "partNumber" : <partNumber>,
  "configuration" : <configString>,
  "categories" : [ { "id": <String>, "name": <string> } ]
}

Note: Categories are only passed from the Release dialog and properties dialogs for now. They are empty when part number generation is called from the BOM table or configuration table.

Expected response sent to Onshape is as follows:

{
  "id" : <partNumberId>,
  "documentId" : <documentId>,
  "elementId" : <elementId>,
  "workspaceId" : <workspaceId>,
  "elementType" : <elementType>,
  "partId" : <partId>,
  "partNumber" : <partNumber>
}

Third-party applications can simply fill the partNumber attribute with the part number generated by the custom numbering scheme and send it as a response. However, the response should at least contain id and partNumber as highlighted above; other attributes are optional.

Custom numbering schemes for part generation, once set in the Release management page, can be invoked from all the places where we set part numbers, including the Release candidate dialog shown below: