Element Right Panel

The element right panel is the panel inside a document that currently houses the BOM, configurations, etc. Applications can use this extension location to add items in this panel.

image alt text

Interaction sequence

The sequence diagram below illustrates the interaction between an Element right panel application extension and the Onshape client:

%%{
  init: {
    "theme": "default",
    "sequence": {
      "mirrorActors": false,
      "showSequenceNumbers": false,
      "width": 75,
      "height": 60,
      "actorMargin": 25,
      "messageFontSize": 13,
      "messageFontFamily": "monospace",
      "messageFontWeight": 2
    }
  }
}%%
sequenceDiagram
  actor user
  participant OSC AS Onshape Client
  participant AE AS Application Extension
  user->>+OSC: start element right panel extension
  Note right of user: via configured button
  OSC->>+AE: invoke action url (with query params)
  AE->>OSC: postMessage(messageName: 'applicationInit')
  loop selection interactions
    user->>OSC: select
    OSC->>AE: postMessage(messageName: 'SELECTION')
  end
  user->>OSC: stop element right panel extension
    Note right of user: via configured button
  deactivate AE
  OSC-XAE: destroy
  deactivate OSC

Supported contexts

  • Part Studio
  • Assembly
  • Document

Supported messages

Each message must include:

message = {
    documentId: documentId,
    workspaceId: workspaceId,
    elementId: elementId,
    messageName: string
};

Where messageName corresponds to one of the supported client messages below:

applicationInit

Send once on application startup.

message = {
    documentId: documentId,
    workspaceId: workspaceId,
    elementId: elementId,
    messageName: 'applicationInit'
};

showMessageBubble

Display a string in the blue message bubble at the top of the application extension.

message = {
    documentId: documentId,
    workspaceId: workspaceId,
    elementId: elementId,
    messageName: 'showMessageBubble',
    message: 'This is a message.'
};

requestViewerImage

Take a screenshot of the current window at the provided image size.

message = {
    documentId: documentId,
    workspaceId: workspaceId,
    elementId: elementId,
    messageName: 'requestViewerImage',
    height: 400,
    width: 400
};

The screenshot is returned as a Blob (see Blob Documentation) in the JSON response:

{
  "messageName": "viewerImage",
  "image": Blob
}

requestSelection

Wait for the user to select the specified entity in the Onshape UI.

This example waits for the user to select 3 faces.

message = {
    documentId: documentId,
    workspaceId: workspaceId,
    elementId: elementId,
    messageName: 'requestSelection',
    messageId: string,
    entityTypeSpecifier: ['FACE'],
    requiredSelectionCount: 3
};

Notes

  • messageId is a unique identifier
  • entityTypeSpecifier must be at least one of:
    entityTypeSpecifier {
  'VERTEX',
  'EDGE',
  'FACE',
  'BODY',
  'DEGENERATE_EDGE',
  'UNKNOWN'
}
  • requiredSelectionCount is the count of selections required to transition from StatusCode.PENDING to StatusCode.SUCCESS. When not included or 0:
    • An unbounded selection count is used
    • A stopRequest message is required to transition from a StatusCode.PENDING to StatusCode.STOPPED
    • The stopRequest response includes the original request’s messageId as stoppedMessageId

requestSelectionHighlight

Highlights the specified entity in the Onshape window. This example highlights the face with ID JHO.

message = {
    documentId: documentId,
    workspaceId: workspaceId,
    elementId: elementId,
    messageName: 'requestSelectionHighlight',
    messageId: string,
    selections: [{
        "selectionType": "ENTITY",
        "selectionId": "JHO",
        "entityType": "FACE"
    }]
};

Notes

  • messageId is a unique identifier
    • If a stopRequest is called, its response includes the original request’s messageId as stoppedMessageId
  • selectionType must be one of:
    selectionType = [
    'ENTITY',
    'BODY',
    'GEOMETRY'
]
  • Call getPartStudioBodyDetails to get the selectionId
  • When selectionType = ENTITY, entityType is required:
    entityType = [
  'VERTEX',
  'EDGE',
  'FACE',
  'BODY',
  'DEGENERATE_EDGE',
  'UNKNOWN'
]
  • When selectionType = BODY, bodyType is required:
    bodyType = [
  'SOLID',
  'SHEET',
  'WIRE',
  'POINT',
  'MATE_CONNECTOR',
  'COMPOSITE',
  'UNKNOWN'
]
  • When selectionType = GEOMETRY, geometryType is required:
    geometryType = [
  'LINE',
  'CIRCLE',
  'ARC',
  'PLANE',
  'CYLINDER',
  'CONE',
  'SPHERE',
  'TORUS',
  'SPLINE',
  'ELLIPSE',
  'MESH',
  'CONIC',
  'REVOLVED',
  'EXTRUDED',
  'ALL_MESH',
  'MIXED_MESH',
  'SPLINE_INTERNAL_POINT',
  'SPLINE_CONTROL_POLYGON',
  'ELLIPTICAL_ARC',
  'UNKNOWN'
]

stopRequest

Transitions a request from StatusCode.PENDING to StatusCode.STOPPED. The response includes the original request’s messageId as stoppedMessageId.

message = {
    documentId: documentId,
    workspaceId: workspaceId,
    elementId: elementId,
    messageName: 'stopRequest'
};

openAnotherElementInCurrentWorkspace

Open the specified element (tab).

message = {
    documentId: documentId,
    workspaceId: workspaceId,
    elementId: elementId,
    messageName: 'openAnotherElementInCurrentWorkspace',
    anotherElementId: 'elementId2'
};

openFeatureDialog

Open the dialog for the specified feature.

message = {
    documentId: documentId,
    workspaceId: workspaceId,
    elementId: elementId,
    messageName: 'openFeatureDialog',
    featureId: 'featureId'
};

To get the featureId call PartStudio/getPartStudioFeatures or Assembly/getFeatures.

closeFeatureDialog

Closes any open feature dialog

message = {
    documentId: documentId,
    workspaceId: workspaceId,
    elementId: elementId,
    messageName: 'closeFeatureDialog',
    accept: false
};

accept=true mimics closing the dialog by clicking the green check mark or Accept button. accept=false mimics closing the dialog by clicking the X or Cancel button to close without saving.

Security considerations

All Security Considerations apply to all Onshape extensions, with the following notes:

  • Initial message from the application extension to the Onshape client, in the form of an applicationInit message (or one of any other messages supported by the element right panel extensions), is required to ensure the Onshape client does not send messages to the extension until it is ready.
  • Once a valid applicationInit message is received by the Onshape client, it will start sending messages with the messageName value SELECTION upon user selection interactions.
  • Prior to accepting any message from the Onshape client as secure, the origin attribute value included in incoming messages must be validated as equal to the original server query parameter value used to load the application extension.