Request

Response

    Hub-Scoped Custom Properties

    Hub-scoped custom properties (HSCP) let a hub administrator define custom properties directly on a hub so they are available to every Component in that hub. Unlike app-managed property definition collections — which are created by an app and then linked to one or more hubs — hub-scoped property definitions are created in the context of a single hub and are managed by that hub’s administrators. This is the simplest way to roll out a consistent set of custom properties across all of an organization’s Design & Make data in a hub.

    Once a hub-scoped property is defined, it is available on the hub for setting a value on a Component — from the Fusion Properties Panel, the BOM, and the GraphQL setProperties mutation.

    For background on property definition collections and the alternative, app-managed workflow, see About Custom Properties and Link Property Definition Collection to a Hub.

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

    When to use hub-scoped properties

    Use hub-scoped custom properties when:

    • You administer a hub and want a custom property to apply to all Components in that hub, without building and maintaining a separate app-managed collection.
    • The property set is specific to one organization or hub rather than shared across many hubs.

    Use an app-managed property definition collection (created with createPropertyDefinitionCollection and linked with linkPropertyDefinitionCollection) when the same property set must be reused across multiple hubs, or when an app owns the property lifecycle.

    Anatomy of a hub-scoped property

    Each hub-scoped property definition describes one custom property:

    • name — The identifier for the property. Must be unique within the hub.
    • specification — The data type the property holds. Hub-scoped properties support STRING, INTEGER, FLOAT, DATE, CURRENCY, PICKLIST, and BOOLEAN (see Supported data types).
    • propertyBehavior — How the value behaves over time. Hub-scoped properties support only STANDARD, where design-impacting values are time-stamped so the value can be tracked historically. TIMELESS is not allowed for hub-scoped properties and is rejected on creation.
    • description — An optional short explanation of the property’s purpose.
    • isHidden — Whether applications should hide the property in their UI.
    • shouldCopy — Whether the property is carried over when a document is copied in Autodesk authoring apps.
    • applicableEntityTypes — The entity types the property applies to. Only COMPONENT is supported.
    • specificationConfig — Type-specific configuration. currencyCode is required when specification is CURRENCY, and picklistOptions is required when specification is PICKLIST.

    Note: The isArchived and isReadOnly metadata fields are not supported for hub-scoped properties.

    Supported data types

    Hub-scoped properties support the following data types:

    Data type (GraphQL)Label used in the UI
    STRING Text
    INTEGER Number
    FLOAT Number with Decimal
    CURRENCY Currency
    DATE Date
    PICKLIST Picklist
    BOOLEAN Checkbox

    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.

    mutation CreateHubScopedPropertyDefinitions($input: CreateHubScopedPropertyDefinitionsInput!) {
      createHubScopedPropertyDefinitions(input: $input) {
        propertyDefinitions {
          results {
            id
            name
            specification
            propertyBehavior
            description
            isHidden
            shouldCopy
            applicableEntityTypes
          }
        }
      }
    }
    
    Show More

    Example variables:

    {
      "input": {
        "hubId": "YOUR_HUB_ID",
        "propertyDefinitionsInput": [
          {
            "name": "Supplier Stock",
            "specification": "INTEGER",
            "propertyBehavior": "STANDARD",
            "description": "On-hand quantity reported by the supplier system.",
            "isHidden": false,
            "shouldCopy": true,
            "applicableEntityTypes": ["COMPONENT"]
          }
        ]
      }
    }
    
    Show More

    The response returns the created property definitions, including their generated id values, which you use when setting property values on Components.

    For a CURRENCY property, supply specificationConfig.currencyCode. For the list of supported values, see the CurrencyCode enum:

    {
      "name": "Vendor Cost",
      "specification": "CURRENCY",
      "propertyBehavior": "STANDARD",
      "applicableEntityTypes": ["COMPONENT"],
      "specificationConfig": {
        "currencyCode": "USD"
      }
    }
    
    Show More

    For a PICKLIST property, supply specificationConfig.picklistOptions with the list of allowed values. Each option requires a display name:

    {
      "name": "Manufacturing Stage",
      "specification": "PICKLIST",
      "propertyBehavior": "STANDARD",
      "applicableEntityTypes": ["COMPONENT"],
      "specificationConfig": {
        "picklistOptions": [
          { "name": "Prototype" },
          { "name": "Pre-production" },
          { "name": "Production" }
        ]
      }
    }
    
    Show More

    A BOOLEAN property holds a true or false value and does not require any specificationConfig:

    {
      "name": "RoHS Compliant",
      "specification": "BOOLEAN",
      "propertyBehavior": "STANDARD",
      "applicableEntityTypes": ["COMPONENT"]
    }
    

    Update hub-scoped property definitions

    Use the updateHubScopedPropertyDefinitions mutation to change attributes of existing hub-scoped property definitions. The description and isHidden fields can be updated; other attributes (such as specification and propertyBehavior) are fixed once the property is created. For a PICKLIST property, you can also update the picklistOptions list, which must contain between 1 and 100 options.

    Localize names and descriptions

    Use the updateHubScopedPropertyDefinitionLocalization mutation to provide translated names and descriptions for a property definition. Supply the hubId, the property definition id, and a list of locale-specific translations. For the list of supported locales, see Support for Localization.

    mutation UpdateHubScopedPropertyDefinitionLocalization($input: UpdateHubScopedPropertyDefinitionLocalizationInput!) {
      updateHubScopedPropertyDefinitionLocalization(input: $input) {
        id
        localizedName
        localizedDescription
      }
    }
    

    Example variables:

    {
      "input": {
        "hubId": "YOUR_HUB_ID",
        "id": "PROPERTY_DEFINITION_ID",
        "localizations": [
          {
            "locale": "fr",
            "name": "Stock fournisseur",
            "description": "Quantité en stock indiquée par le système fournisseur."
          }
        ]
      }
    }
    
    Show More

    Delete a hub-scoped property definition

    Use the deleteHubScopedPropertyDefinition mutation to remove a property definition from a hub. Provide the hubId and the propertyDefinitionId.

    Warning: Deletion is permanent and irreversible. It removes the property definition and all of its values across the entire hub.

    mutation DeleteHubScopedPropertyDefinition($input: DeleteHubScopedPropertyDefinitionInput!) {
      deleteHubScopedPropertyDefinition(input: $input) {
        propertyDefinitionId
      }
    }
    

    Set values on Components

    Once a hub-scoped property is defined, use the setProperties mutation to set or clear its value on a Component, referencing the property definition id returned at creation time. Values can also be set by end users in Autodesk Fusion clients.

    Read a hub’s custom properties

    Hub-scoped property definitions are read through the same APIs as any other property definition. When the first hub-scoped property is created, a property definition collection of type HUB is automatically created for the hub — administrators do not create or link this collection themselves. This differs from app-managed (third-party) custom properties, where a developer must explicitly create a collection with createPropertyDefinitionCollection and link it with linkPropertyDefinitionCollection before defining properties.

    To list a hub’s hub-scoped definitions, query the hub’s propertyDefinitionCollections and inspect the HUB-type collection and its property definitions.

    Limits and behaviors

    • Per-hub limit — Each hub supports up to 500 hub-scoped property definitions. Creation is blocked with a clear message once the limit is reached.
    • Per-call limit — A single createHubScopedPropertyDefinitions call can create up to 30 property definitions.
    • Unique names — Property names must be unique within the hub’s hub-scoped property set.
    • Not supported — The isArchived and isReadOnly fields are not available for hub-scoped properties.

    Reference

    For full argument and input-type details, see the API Reference for each operation: