Associativity

Onshape does not expose a persistent ID for any of these entities. When the model changes, the ID may change. Therefore, Onshape provides an API to enable mapping IDs from a previous microversion to the current microversion. Assuming a simple case of maintaining associativity for a face, an abstract workflow might be:

  1. Read the tessellated model data.
  2. Select the face of interest.
  3. Store the Face ID and Document Microversion ID for the face.
  4. [ user changes model ]
  5. Call the REST API to translate from the known Face ID to an ID in the new model.
  6. Re-apply application-specific data to the face(s) in the new model. Note that a face may become zero, one or multiple faces in the new model, depending on what changes the user made.

Associativity Example

  1. Create a cube in Onshape:
    image alt text
  2. Get the document microversion ID from the URL: https://cad.onshape.com/api/d/<docid>/w/<wid>/microversionId.
  3. Use the appropriate REST API to get the tessellated faces (getPartStudioFaces) and edges (getPartStudioEdges}. Note the ids:
    • Part ID: JHD
    • Front face ID: JHO
    • Top edge of the front face ID: JHd
    • Right edge of the top face ID: JHt
  4. Split cube with the Front plane and translate the IDs:

image alt text

POST

https://cad.onshape.com/api/partstudios/d/<docid>/w/<wid>/e/<eid>/idtranslations

Body:

{
  "sourceDocumentMicroversion" : "47e75ab2ee8b4356a76ebd47",
  "ids" : ["JHD", "JHO", "JHd", "JHt"  ]
}

Response:

{
    "documentId": "748d6e850c9248328189922b",
    "elementId": "042a6fa54e79451e8076463d",
    "sourceDocumentMicroversion": "47e75ab2ee8b4356a76ebd47",
    "ids": [
        { "source": "JHD", "status": "SPLIT", "target": ["JID", "JIH"] },
        { "source": "JHO", "status": "OK", "target": ["JHO"] },
        { "source": "JHd", "status": "OK", "target": ["JHd"] },
        { "source": "JHt", "status": "SPLIT", "target": ["JI5", "JI9"] }
    ],
    "targetDocumentMicroversion": "78bc7f3fcf82475085c2f3ab"
}
  1. Delete one of the parts, and translate the IDs:

image alt text

POST

https://cad.onshape.com/api/partstudios/d/<docid>/w/<wid>/e/<eid>/idtranslations

Body:

{
  "sourceDocumentMicroversion" : "47e75ab2ee8b4356a76ebd47",
  "ids" : ["JHD", "JHO", "JHd", "JHt"]
}

Response:

{
    "documentId": "748d6e850c9248328189922b",
    "elementId": "042a6fa54e79451e8076463d",
    "sourceDocumentMicroversion": "47e75ab2ee8b4356a76ebd47",
    "ids": [
        { "source": "JHD", "status": "OK", "target": ["JID"] },
        { "source": "JHO", "status": "FAILED_TO_RESOLVE", "target": [] },
        { "source": "JHd", "status": "FAILED_TO_RESOLVE", "target": [] },
        { "source": "JHt", "status": "OK", "target": ["JI5"] }
    ],
    "targetDocumentMicroversion": "52aa74d34b624f3aaef33204"
}
  1. Roll back the delete and the split, and translate the IDs:

image alt text

POST

https://cad.onshape.com/api/partstudios/d/<docid>/w/<wid>/e/<eid>/idtranslations

Body:

{
  "sourceDocumentMicroversion" : "47e75ab2ee8b4356a76ebd47",
  "ids" : ["JHD", "JHO", "JHd", "JHt"]
}

Response:

{
    "documentId": "748d6e850c9248328189922b",
    "elementId": "042a6fa54e79451e8076463d",
    "sourceDocumentMicroversion": "47e75ab2ee8b4356a76ebd47",
    "ids": [
        { "source": "JHD", "status": "OK", "target": ["JID"] },
        { "source": "JHO", "status": "OK", "target": ["JHO"] },
        { "source": "JHd", "status": "OK", "target": ["JHd"] },
        { "source": "JHt", "status": "OK", "target": ["JHt"] }
    ],
    "targetDocumentMicroversion": "52aa74d34b624f3aaef33204"
}