Request

Response

    Manage Hub-Scoped Custom Properties

    This topic provides instructions on how to define and use hub-scoped custom properties (HSCP) with the Manufacturing Data Model API. You will learn how to:

    • Create one or more hub-scoped property definitions on a hub
    • Read the hub-scoped property definitions back to verify them
    • Set a hub-scoped property value on a component

    For a conceptual overview of hub-scoped custom properties, see Hub-Scoped Custom Properties.

    Note: Creating and managing hub-scoped property definitions requires a hub administrator with Fusion Manage.

    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:

    Step 1 - Create Hub-Scoped Property Definitions

    Use the createHubScopedPropertyDefinitions mutation to create up to 30 property definitions on a hub in a single call. Provide the hubId and a list of property definitions in propertyDefinitionsInput. Each created definition returns a generated id, which you use in Step 2 and Step 3.

    1. In Manufacturing Data Model Explorer, enter the following mutation in the Query Pane:

      Mutation

      mutation CreateHubScopedPropertyDefinitions($input: CreateHubScopedPropertyDefinitionsInput!) {
         createHubScopedPropertyDefinitions(input: $input) {
            propertyDefinitions {
               results {
                  id
                  name
                  specification
                  propertyBehavior
                  description
                  isHidden
                  shouldCopy
                  applicableEntityTypes
               }
            }
         }
      }
      
      Show More
    2. In the Query Variables Pane, enter the hubId and the property definitions you want to create. To know how to obtain the hubId, refer to Retrieve Hubs.

      • name: A name that is unique within the hub’s hub-scoped property set.
      • specification: One of the supported data types — STRING, INTEGER, FLOAT, DATE, or CURRENCY.
      • propertyBehavior: Set to STANDARD. TIMELESS is not supported for hub-scoped properties.
      • applicableEntityTypes: The entity types the property applies to. Only COMPONENT is supported.

        Note: For a CURRENCY property, you must also supply specificationConfig.currencyCode (for example, USD).

      Query Variables

      {
         "input": {
            "hubId": "urn:adsk.ace:beta.scope:02dd340f-3e84-4db8-b6a1-56a964a202c7",
            "propertyDefinitionsInput": [
               {
                  "name": "Supplier Code",
                  "specification": "STRING",
                  "propertyBehavior": "STANDARD",
                  "description": "Supplier identifier from the ERP system.",
                  "isHidden": false,
                  "shouldCopy": true,
                  "applicableEntityTypes": ["COMPONENT"]
               }
            ]
         }
      }
      
      Show More
    3. Click Play. The response returns the created property definitions, including their generated id values.

      Response

      {
         "data": {
            "createHubScopedPropertyDefinitions": {
               "propertyDefinitions": {
                  "results": [
                     {
                        "id": "cHJvcGRlZn4yMTU5NTk2Nn4yMTU5NTk2Nl9IU0NQfjIxNTk1OTY2X0hTQ1B-cGFyYW1ldGVycy4yMTU5NTk2NjphODQ0NzhiOTI2YTU0YjE2OTJiOGJlMjg5NzI3MTIzOS0xLjAuMA",
                        "name": "Supplier Code",
                        "specification": "STRING",
                        "propertyBehavior": "STANDARD",
                        "description": "Supplier identifier from the ERP system.",
                        "isHidden": false,
                        "shouldCopy": true,
                        "applicableEntityTypes": ["COMPONENT"]
                     }
                  ]
               }
            }
         }
      }
      
      Show More

    Note: Save the id of the created property definition. You will need it as the propertyDefinitionId when setting a value in Step 3.

    Step 2 - Verify the Created Property Definition

    Hub-scoped property definitions are read through the same APIs as any other property definition. Query the hub’s propertyDefinitionCollections and use the definitions filter to retrieve the definition you created in Step 1 by its id.

    1. In Manufacturing Data Model Explorer, enter the following query in the Query Pane:

      Query

      query GetHubScopedPropertyDefinition($hubId: ID!, $filter: PropertyDefinitionFilterInput) {
         hub(hubId: $hubId) {
            id
            propertyDefinitionCollections {
               results {
                  id
                  name
                  definitions(filter: $filter) {
                     results {
                        id
                        name
                        specification
                        propertyBehavior
                        isHidden
                        shouldCopy
                        description
                        applicableEntityTypes
                     }
                  }
               }
            }
         }
      }
      
      Show More
    2. In the Query Variables Pane, enter the hubId and the property definition id obtained in Step 1.

      Query Variables

      {
         "hubId": "urn:adsk.ace:beta.scope:02dd340f-3e84-4db8-b6a1-56a964a202c7",
         "filter": {
            "ids": ["cHJvcGRlZn4yMTU5NTk2Nn4yMTU5NTk2Nl9IU0NQfjIxNTk1OTY2X0hTQ1B-cGFyYW1ldGVycy4yMTU5NTk2NjphODQ0NzhiOTI2YTU0YjE2OTJiOGJlMjg5NzI3MTIzOS0xLjAuMA"]
         }
      }
      
    3. Click Play. The response returns the matching hub-scoped property definition under the hub’s HUB-type property definition collection.

      Response

      {
         "data": {
            "hub": {
               "id": "urn:adsk.ace:beta.scope:02dd340f-3e84-4db8-b6a1-56a964a202c7",
               "propertyDefinitionCollections": {
                  "results": [
                     {
                        "id": "cHJvcGRlZmNvbH4yMTU5NTk2Nn4yMTU5NTk2Nl9IU0NQfjIxNTk1OTY2X0hTQ1A",
                        "name": "Custom Properties",
                        "definitions": {
                           "results": [
                              {
                                 "id": "cHJvcGRlZn4yMTU5NTk2Nn4yMTU5NTk2Nl9IU0NQfjIxNTk1OTY2X0hTQ1B-cGFyYW1ldGVycy4yMTU5NTk2NjphODQ0NzhiOTI2YTU0YjE2OTJiOGJlMjg5NzI3MTIzOS0xLjAuMA",
                                 "name": "Supplier Code",
                                 "specification": "STRING",
                                 "propertyBehavior": "STANDARD",
                                 "isHidden": false,
                                 "shouldCopy": true,
                                 "description": "Supplier identifier from the ERP system.",
                                 "applicableEntityTypes": ["COMPONENT"]
                              }
                           ]
                        }
                     }
                  ]
               }
            }
         }
      }
      
      Show More

    Note: The HUB-type property definition collection that holds your hub-scoped definitions is created automatically when the first hub-scoped property is created. Unlike app-managed (third-party) custom properties, you do not create or link this collection yourself.

    Step 3 - Set a Hub-Scoped Property Value on a Component

    Use the setProperties mutation to assign a value to the hub-scoped property on a component. Each entry in propertyInputs references the property by the propertyDefinitionId obtained in Step 1 and provides the new value.

    1. In Manufacturing Data Model Explorer, enter the following mutation in the Query Pane:

      Mutation

      mutation SetHubScopedProperty($input: SetPropertiesInput!) {
         setProperties(input: $input) {
            targetId
            properties {
               value
               displayValue
               definition {
                  id
                  name
                  propertyBehavior
               }
            }
         }
      }
      
      Show More
    2. In the Query Variables Pane, enter the targetId (the component ID), the propertyDefinitionId from Step 1, and the new value. To know how to obtain the componentId, refer to Retrieve Items.

      Query Variables

      {
         "input": {
            "targetId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35aaFFydzlvREt1OGtpRUs0b1Q1UENIX2FnYQ",
            "propertyInputs": [
               {
                  "propertyDefinitionId": "cHJvcGRlZn4yMTU5NTk2Nn4yMTU5NTk2Nl9IU0NQfjIxNTk1OTY2X0hTQ1B-cGFyYW1ldGVycy4yMTU5NTk2NjphODQ0NzhiOTI2YTU0YjE2OTJiOGJlMjg5NzI3MTIzOS0xLjAuMA",
                  "value": "ACME-001"
               }
            ]
         }
      }
      
      Show More

    Note: To clear a hub-scoped property value rather than overwrite it, set the value field to null in the propertyInputs entry.

    1. Click Play. The response confirms the new value and echoes the property definition.

      Response

      {
         "data": {
            "setProperties": {
               "targetId": "cHJvZHVjdH53TTBJUmZ2ZzNPVUtMdmxiMnh0Mkx0X0wyQ35aaFFydzlvREt1OGtpRUs0b1Q1UENIX2FnYQ",
               "properties": [
                  {
                     "value": "ACME-001",
                     "displayValue": "ACME-001",
                     "definition": {
                        "id": "cHJvcGRlZn4yMTU5NTk2Nn4yMTU5NTk2Nl9IU0NQfjIxNTk1OTY2X0hTQ1B-cGFyYW1ldGVycy4yMTU5NTk2NjphODQ0NzhiOTI2YTU0YjE2OTJiOGJlMjg5NzI3MTIzOS0xLjAuMA",
                        "name": "Supplier Code",
                        "propertyBehavior": "STANDARD"
                     }
                  }
               ]
            }
         }
      }
      
      Show More

    Additional Notes

    • Update: Use the updateHubScopedPropertyDefinitions mutation to change a definition’s description or isHidden flag. Other attributes (such as specification and propertyBehavior) are fixed once the property is created.
    • Localize: Use the updateHubScopedPropertyDefinitionLocalization mutation to provide translated names and descriptions for a definition.
    • Delete: Use the deleteHubScopedPropertyDefinition mutation to remove a definition. Deletion is permanent and irreversible, and removes the property definition and all of its values across the entire hub.
    • Limits: Each hub supports up to 500 hub-scoped property definitions, and a single createHubScopedPropertyDefinitions call can create up to 30 definitions. Property names must be unique within the hub’s hub-scoped property set.