Drawings

The messages described on this page can be sent from any extension within an Onshape drawing.

Example of an Element right panel extension with an Inside drawing context.

Supported messages

Each message must include:

message = {
    documentId: documentId,
    workspaceId: workspaceId,
    elementId: elementId,
    messageName: string,
    messageId?: string
}

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

Optionally, send a unique messageId to correlate the message with the response.

applicationInit

Send once on application startup.

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

drawingSelectEntities

Specify entities in the drawing to select.

message = {
  documentId: documentId,
  workspaceId: workspaceId,
  elementId: elementId,
  messageName: 'drawingSelectEntities',
  messageId: string,
  selections: [
    {
      type: 'ENTITY',
      id: 'h:000100'
    },
    {
      type: 'ENTITY',
      id: 'h:000101'
    }
  ]
}

Notes

• selections.id: Export the drawing to JSON to obtain logicalId of the entities to select.

drawingHighlightEntities

Highlight entities in the drawing window.

message = {
  documentId: documentId,
  workspaceId: workspaceId,
  elementId: elementId,
  messageName: 'drawingHighlightEntities',
  messageId: string,
  selections: [
    {
      type: 'ENTITY',
      id: 'h:000100'
    },
    {
      type: 'EDGE',
      id: 'f1234', 
      viewId: 'v1234'
    }
  ]
}

Notes

• selections.type must be one of: ENTITY | EDGE
• For selections.type = ENTITY:
  • selections.id: Export the drawing to JSON to obtain logicalId of the entity to select.
• For selections.type = EDGE:
  • selections.viewId: Call getDrawingViews to get the viewId for the edge.
  • selections.id: Call getDrawingViewJsonGeometry to get the uniqueId for the edge.

drawingActivateSheet

Switch between sheets in the drawing.

message = {
  documentId: documentId,
  workspaceId: workspaceId,
  elementId: elementId,
  messageName: 'drawingActivateSheet',
  messageId: string,
  sheet: { name: string }
}

Notes

• sheet can be any of:
  • sheet: { name: string }
  • sheet: { logicalId: string }
  • sheet: { index: number }
• sheet: Export the drawing to JSON to obtain the name, logicalId, or index.

Security considerations

The extension security considerations apply to all Onshape extensions. Additionally:

• An initial applicationInit message must be sent from the application extension to the Onshape client to ensure Onshape does not send messages to the extension until it is ready.
• Once a valid applicationInit message is received by the Onshape client, it starts sending messages with messageName=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.