Request

Response

    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:

    1. Retrieve Hubs.
    2. Retrieve Projects.
    3. Retrieve Folders.
    4. Retrieve Items.

    You will use the following operations in this topic:

    TypeOperationDescription
    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.

    1. 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
    2. In the Query Variables Pane, enter the value of the componentId. To know how to obtain the componentId, refer to Retrieve Items.

      Query Variables

      {
         "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35aaFFydzlvREt1OGtpRUs0b1Q1UENIX2FnYQ"
      }
      
    3. 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.

    1. 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
    2. In the Query Variables Pane, enter the componentId and the list of base property names you want to retrieve. Names must match the labels listed in Base Properties.

      Query Variables

      {
         "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35aaFFydzlvREt1OGtpRUs0b1Q1UENIX2FnYQ",
         "names": ["Manufacturer", "Manufacturer Part Number"]
      }
      
    3. 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.

    1. 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
    2. In the Query Variables Pane, enter the targetId (the component ID), the propertyDefinitionId for the base property you want to update, and the new value.

      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.

    1. 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.

    1. 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
    2. In the Query Variables Pane, enter the componentId and the name of the base property you updated in Step 3.

      Query Variables

      {
         "componentId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35aaFFydzlvREt1OGtpRUs0b1Q1UENIX2FnYQ",
         "names": ["Manufacturer"]
      }
      
    3. 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 baseProperties field is also exposed on Drawing. The same baseProperties { results { ... } } selection applies, and the setProperties mutation shown above accepts a drawing ID as targetId. To retrieve a drawing’s base properties, replace the component query above with the drawing query.
    • Read-only base properties: A small number of base properties (such as Unit of Measure) are read-only. Inspect the definition.isReadOnly flag 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.filter accepts both ids and names. See PropertyFilterInput for the full input shape.