Retrieve and Update Base Properties
This topic provides instructions on how to read and modify base properties on a component using the Manufacturing Data Model API. You will learn how to:
- Retrieve all base properties for a component
- Filter the response to a specific subset of base properties by name
- Update the value of a base property
- Verify the updated value on the component
For a conceptual overview of base properties, see Base Properties.
As a prerequisite for completing the current topic, you need to complete the following tasks:
You will use the following operations in this topic:
| Type | Operation | Description |
|---|---|---|
| Query | component | Retrieves a component and its base properties. |
| Mutation | setProperties | Sets one or more property values on a target. |
Step 1 - Retrieve Base Properties for a Component
The component query exposes a baseProperties field that returns the complete set of base properties present on the component. The definition of each property includes its id (used to update the value in Step 3) and an isReadOnly flag indicating whether the value can be modified through the API.
- In Manufacturing Data Model Explorer, enter the following query in the Query Pane:
Query
query GetBaseProperties($componentId: ID!) { component(componentId: $componentId) { id name { value } baseProperties { results { name value displayValue definition { id name isReadOnly specification } } } } }Show More - In the Query Variables Pane, enter the value of the
componentId. To know how to obtain thecomponentId, refer to Retrieve Items.Query Variables
{ "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35aaFFydzlvREt1OGtpRUs0b1Q1UENIX2FnYQ" } - Click Play. The response lists every base property on the component, along with each property’s current value and definition.
Response
{ "data": { "component": { "id": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35aaFFydzlvREt1OGtpRUs0b1Q1UENIX2FnYQ", "name": { "value": "Espresso Machine" }, "baseProperties": { "results": [ { "name": "Manufacturer", "value": "Acme", "displayValue": "Acme", "definition": { "id": "cHJvcGRlZn5RbUZ6WlZCeWIzQmxjblJwWlhOVGRHRm5hVzVuflFtRnpaVkJ5YjNCbGNuUnBaWE5IY205MWNGTjBZV2RwYm1jflEyOXRjRzl1Wlc1MH5wYXJhbWV0ZXJzLlFtRnpaVkJ5YjNCbGNuUnBaWE5UZEdGbmFXNW46ZTM1NDM5ZTJlMDI0NDhjYTgyNWQ0MTI4MTY4NDJlY2ItMS4wLjA", "name": "Manufacturer", "isReadOnly": false, "specification": "STRING" } }, { "name": "Unit of Measure", "value": "each", "displayValue": "Each", "definition": { "id": "cHJvcGRlZn5RbUZ6WlZCeWIzQmxjblJwWlhOVGRHRm5hVzVuflVuaXRPZk1lYXN1cmV-cGFyYW1ldGVycy5RbUZ6WlZCeWIzQmxjblJwWlhOVGRHRm5hVzVuOjEtMS4wLjA", "name": "Unit of Measure", "isReadOnly": true, "specification": "STRING" } } ] } } } }Show More
Note: Save the definition.id of the property you intend to update. You will need it as the propertyDefinitionId in Step 3. If isReadOnly is true, the value cannot be changed through the API; Unit of Measure is one such property.
Step 2 - Filter to Specific Base Properties (Optional)
The baseProperties field accepts a filter argument of type PropertyFilterInput. Use names to limit the response to the base properties you actually need, which keeps payloads small when the component has many properties.
- In Manufacturing Data Model Explorer, enter the following query in the Query Pane:
Query
query GetSpecificBaseProperties($componentId: ID!, $names: [String!]) { component(componentId: $componentId) { id baseProperties(filter: { names: $names }) { results { name displayValue definition { id isReadOnly } } } } }Show More - In the Query Variables Pane, enter the
componentIdand the list of base propertynamesyou want to retrieve. Names must match the labels listed in Base Properties.Query Variables
{ "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35aaFFydzlvREt1OGtpRUs0b1Q1UENIX2FnYQ", "names": ["Manufacturer", "Manufacturer Part Number"] } - Click Play. The response includes only the base properties whose names you specified.
Response
{ "data": { "component": { "id": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35aaFFydzlvREt1OGtpRUs0b1Q1UENIX2FnYQ", "baseProperties": { "results": [ { "name": "Manufacturer", "displayValue": "Acme", "definition": { "id": "cHJvcGRlZn5RbUZ6WlZCeWIzQmxjblJwWlhOVGRHRm5hVzVuflFtRnpaVkJ5YjNCbGNuUnBaWE5IY205MWNGTjBZV2RwYm1jflEyOXRjRzl1Wlc1MH5wYXJhbWV0ZXJzLlFtRnpaVkJ5YjNCbGNuUnBaWE5UZEdGbmFXNW46ZTM1NDM5ZTJlMDI0NDhjYTgyNWQ0MTI4MTY4NDJlY2ItMS4wLjA", "isReadOnly": false } }, { "name": "Manufacturer Part Number", "displayValue": "ESP-001", "definition": { "id": "cHJvcGRlZn5RbUZ6WlZCeWIzQmxjblJwWlhOVGRHRm5hVzVuflBhcnROdW1iZXJ-cGFyYW1ldGVycy5RbUZ6WlZCeWIzQmxjblJwWlhOVGRHRm5hVzVuOjItMS4wLjA", "isReadOnly": false } } ] } } } }Show More
Note: Pagination is currently not supported on baseProperties; the API returns all matching base properties in a single response.
Step 3 - Update a Base Property Value
Use the setProperties mutation to assign a new value to one or more base properties on a component. Each entry in propertyInputs references a base property by its propertyDefinitionId (collected in Step 1) and provides the new value. Updating a base property creates a new version of the component on which it is set.
- In Manufacturing Data Model Explorer, enter the following mutation in the Query Pane:
Mutation
mutation SetBaseProperties($input: SetPropertiesInput!) { setProperties(input: $input) { targetId properties { value displayValue definition { name isReadOnly propertyBehavior } } } }Show More - In the Query Variables Pane, enter the
targetId(the component ID), thepropertyDefinitionIdfor the base property you want to update, and the newvalue.Query Variables
{ "input": { "targetId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35aaFFydzlvREt1OGtpRUs0b1Q1UENIX2FnYQ", "propertyInputs": [ { "propertyDefinitionId": "cHJvcGRlZn5RbUZ6WlZCeWIzQmxjblJwWlhOVGRHRm5hVzVuflFtRnpaVkJ5YjNCbGNuUnBaWE5IY205MWNGTjBZV2RwYm1jflEyOXRjRzl1Wlc1MH5wYXJhbWV0ZXJzLlFtRnpaVkJ5YjNCbGNuUnBaWE5UZEdGbmFXNW46ZTM1NDM5ZTJlMDI0NDhjYTgyNWQ0MTI4MTY4NDJlY2ItMS4wLjA", "value": "Autodesk" } ] } }Show More
Note: To clear a base property value rather than overwrite it, set the value field to null in the propertyInputs entry. Read-only base properties (isReadOnly: true) cannot be modified through this mutation; attempting to set one will return an error.
- Click Play. The response confirms the new value and echoes the property definition.
Response
{ "data": { "setProperties": { "targetId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35aaFFydzlvREt1OGtpRUs0b1Q1UENIX2FnYQ", "properties": [ { "value": "Autodesk", "displayValue": "Autodesk", "definition": { "name": "Manufacturer", "isReadOnly": false, "propertyBehavior": "STANDARD" } } ] } } }Show More
Step 4 - Verify the Updated Value
Re-run the query from Step 1 (or the filtered query from Step 2) against the same componentId to confirm that the new value is now reflected on the component.
- In Manufacturing Data Model Explorer, enter the following query in the Query Pane:
Query
query VerifyBaseProperty($componentId: ID!, $names: [String!]) { component(componentId: $componentId) { id baseProperties(filter: { names: $names }) { results { name displayValue } } } }Show More - In the Query Variables Pane, enter the
componentIdand the name of the base property you updated in Step 3.Query Variables
{ "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35aaFFydzlvREt1OGtpRUs0b1Q1UENIX2FnYQ", "names": ["Manufacturer"] } - Click Play. The response reflects the updated value.
Response
{ "data": { "component": { "id": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35aaFFydzlvREt1OGtpRUs0b1Q1UENIX2FnYQ", "baseProperties": { "results": [ { "name": "Manufacturer", "displayValue": "Autodesk" } ] } } } }Show More
Additional Notes
- Drawings: The
basePropertiesfield is also exposed on Drawing. The samebaseProperties { results { ... } }selection applies, and thesetPropertiesmutation shown above accepts a drawing ID astargetId. To retrieve a drawing’s base properties, replace thecomponentquery above with thedrawingquery. - Read-only base properties: A small number of base properties (such as
Unit of Measure) are read-only. Inspect thedefinition.isReadOnlyflag returned by Step 1 before attempting to update a property. - Versioning: Updating a base property creates a new version of the component or drawing on which it is set. To inspect the resulting history change, see Track Object History.
- Filtering:
baseProperties.filteraccepts bothidsandnames. See PropertyFilterInput for the full input shape.