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:
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.
- 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 - In the Query Variables Pane, enter the
hubIdand the property definitions you want to create. To know how to obtain thehubId, 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, orCURRENCY. - propertyBehavior: Set to
STANDARD.TIMELESSis not supported for hub-scoped properties. - applicableEntityTypes: The entity types the property applies to. Only
COMPONENTis supported.Note: For a
CURRENCYproperty, you must also supplyspecificationConfig.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 - Click Play. The response returns the created property definitions, including their generated
idvalues.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.
- 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 - In the Query Variables Pane, enter the
hubIdand the property definitionidobtained in Step 1.Query Variables
{ "hubId": "urn:adsk.ace:beta.scope:02dd340f-3e84-4db8-b6a1-56a964a202c7", "filter": { "ids": ["cHJvcGRlZn4yMTU5NTk2Nn4yMTU5NTk2Nl9IU0NQfjIxNTk1OTY2X0hTQ1B-cGFyYW1ldGVycy4yMTU5NTk2NjphODQ0NzhiOTI2YTU0YjE2OTJiOGJlMjg5NzI3MTIzOS0xLjAuMA"] } } - 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.
- 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 - In the Query Variables Pane, enter the
targetId(the component ID), thepropertyDefinitionIdfrom Step 1, and the newvalue. To know how to obtain thecomponentId, 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.
- 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
descriptionorisHiddenflag. Other attributes (such asspecificationandpropertyBehavior) 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
createHubScopedPropertyDefinitionscall can create up to 30 definitions. Property names must be unique within the hub’s hub-scoped property set.