# Onshape

Parts, released revisions, assemblies and drawings from Onshape

- Category: Apps
- Runs in: the Phloem cloud

Puts your Onshape parts, revisions, assemblies and drawings in Trace, so Hamming can cite the exact revision a test used. With your approval, Hamming can also change the model.

## What Phloem reads
- **Documents** — all the key can see, or the ones you pick
- **Parts** — name, part number, description, material, mass, and your company's own part properties (Vendor, Cost, Finish…)
- **Released revisions first** — a released part, assembly or drawing is read at its release, with its revision letter and whether it is released or obsolete. One never released is read at the document's latest version.
- **Configured parts** — a part released in a configuration becomes its own record
- **Assemblies** — the top level of each bill of materials, with quantities
- **Drawings** — linked to the parts and assemblies they show
- **PCB Studio and Simulation tabs** — kept so they can be cited, but not read further

## What you need
- An Onshape API key (access key and secret key). Create it at **dev-portal.onshape.com → API keys**. It reads what its user can read.
- **Read** scope to keep Onshape in Trace. Add **write** scope so Hamming can make changes.
- For release state, Onshape release management (Professional or Enterprise plan). Without it, parts still sync, with no release state.

## Connect
1. In the console, open **Connectors**, choose **Add connector**, then **Onshape**.
2. Enter **Access key** and **Secret key**. Fill in **Onshape URL** only if your Enterprise has its own domain (e.g. `https://acme.onshape.com`).
3. Phloem checks the key. If its user belongs to more than one company, pick the **Company**.
4. Pick the **Documents** to keep in Trace. Pick none to keep every document the key lists.
5. Name and save the connection.

## What Hamming can do
Read:
- **Documents** — search the documents the key can see by name
- **Part** — all of a part's properties and mass properties, now or at a version
- **BOM** — an assembly's items, part numbers and quantities
- **Features** — a Part Studio's features in order, and its variables
- **Evaluate** — run FeatureScript on a Part Studio and return the value (read only)
- **Versions** — a document's saved versions

Change:
- **Set properties** — part number, description, vendor… by your company's property names
- **Set variables** — in a Part Studio or Variable Studio
- **Update feature** — change one feature's parameters
- **Create version** — save a version of a document

Remove:
- **Delete feature**

**API request** reaches any Onshape REST call. GET is a read, POST/PUT/PATCH a change, DELETE a removal.

On the connector's page, an admin sets what Hamming may change: **Allowed**, **Needs approval** (the default: Hamming asks before each change) or **Off**. A removal always asks.

## Notes
- With no documents picked, each sync reads at most 200 documents.
- Hamming changes the document's workspace. Trace reads released revisions and saved versions, so a change shows in Trace once a version is saved (**Create version**).
- A document deleted or moved to the trash leaves Trace. One the key can no longer read stays as it was.
- **Keep in Trace** and **Sync now** are on the connector's page.

## Connection fields

| Field | Type | Required | Notes |
|---|---|---|---|
| Access key | Text | Yes | Create an API key at dev-portal.onshape.com → API keys. Read scope to keep it in Trace; write scope too for the agent to make changes. |
| Secret key | Secret | Yes |  |
| Documents | Any of | No | Leave empty to read the documents the key lists (up to 200). |
| Company id | Text | No | Only when the key's user belongs to more than one company. |
| Onshape URL | Text | No | Only for an Enterprise's own domain, e.g. https://acme.onshape.com. |