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.

App development workflow

To create an app that opens in the Onshape UI for internal use or testing:

1. Register the app with Onshape.
2. Create an extension for the app in the Onshape UI.
3. Create an app store entry.
4. Subscribe to the app.
   • Company, Classroom, and Enterprise admins can assign internal users, aliases, and teams to apps in their Developer Settings without having to create a store entry.

See Hello World for an example.

To publish the app to the Onshape App Store for end users:

1. Authenticate with OAuth2.
2. Complete the Launch Checklist.

Create an extension

You must first create an application before adding an extension.

1. Do one of the following:
   • Company/Classroom/Enterprise admins should go to their Developer Settings.
   • Users with individual accounts should go to their Developer Portal.
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.

Security considerations

To ensure security, an application extension must:

• Parse for document, workspace, and element IDs: Parse for the documentId, workspaceId, and elementId that were passed as query parameters within the application extension’s iframe src URL. You must post these back in each POST message.
• Parse for the server: Parse for the server that was passed as a query parameter within the application extension’s iframe src URL. You must use this to validate messages received.
  • If the application extension uses a JavaScript library or framework (e.g., BackboneJS or AngularJS), it can parse the query parameters and maintain state in other ways.
• Not redirect to another base URL: The browser tells the Onshape client the origin base URL from which a POST message is received. The Onshape client ignores messages posted from an origin URL that doesn’t match the original iframe src URL. It is extremely important to the security of your application that you verify that the origin of all messages you receive is the same as the original server query parameter in the iframe src (i.e., if (server === e.origin)). In production operation especially, the message IS NOT SAFE if the message origin does not match the iframe src server query parameter. Application extensions should not redirect to another base URL after the iframe has been opened, or the messages will be ignored.
• Post a message on startup: Onshape will not post messages until a newly started application extension has first posted a valid message to Onshape. This constraint is in effect anytime an application extension is (re)started and exists to avoid posting messages to application extensions that are not ready to handle them, are not fully loaded, etc. After your application extension is fully loaded and ready to receive messages, post a message to Onshape. A keepAlive message is a great first message to send to Onshape. Once Onshape receives a valid message, Onshape will start posting messages to the application extension. If the application extension later sends an invalid message Onshape will stop sending messages until a valid message is posted to Onshape.

POST messages submitted by application extensions to Onshape will be ignored if any of the following are true:

• The documentId, workspaceId, or elementId are missing or not valid.
• The message name is missing or not recognized.
• The origin of the POST message does not match the original iframe src URL.

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

See also: Element tab extensions

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: