PTC ConfigurableLinks Domain
The ConfigurableLinks domain allows customers to define custom object-to-object relationships beyond the standard out-of-the-box links provided by PTC. These links are modeled as types and must be subtyped for use in real-world scenarios.
The ConfigurableLinks domain in WRS supports read, create, update, and delete operations for configurable links, enabling you to query, create, modify, and remove configurable link instances using RESTful APIs.
In addition to single-object operations, Windchill REST Services also support multi-object (bulk) operations for configurable links, enabling you to create, update, and delete multiple configurable link instances in a single request.
 |
You can perform create, update, and delete operations through role-based navigation properties generated on the configurablelinkable entity types.
These navigation properties primarily support single-object operations, where each request processes one configurable link instance. Multi-object operations extend this capability and are supported through bound actions on the configurablelinkable entities.
|
The configurable link types are represented as the following OData entity types:
|
Items
|
OData Entities
|
|---|---|
|
Configurable Describe Link
|
ConfigurableDescribeLink
|
|
Configurable Reference Link
|
ConfigurableReferenceLink
|
|
Configurable Masters Link
|
ConfigurableMastersLink
|
|
Configurable Revision Link
|
ConfigurableRevisionLink
|
Key characteristics of these entities are:
• Soft types and soft attributes are supported.
• These entity types are defined in a new ConfigurableLinks domain, which includes only entity types (no entity sets) and imports the PTC domain.
Each configurable link type defines navigation to RoleA and RoleB. The navigation names mirror the role names in the Type Manager, and their targets are WindchillEntities. The navigation properties defined between configurable link entities and their RoleA and RoleB objects support read, create, update, and delete operations on configurable link instances, depending on the link type and access controls.
Multi-object operations extend these capabilities by enabling bulk processing while reusing the same navigation model, validation rules, and access control behavior.
Type casting is supported when the type is available in the EDM. Configurable links can be used with most Windchill entities, including:
• Parts
• Documents
• CADDocuments
• ChangeItems
• RegSubmission2
Multi-Object Operations for Configurable Links
In addition to single-object operations, Windchill REST Services support multi-object (bulk) operations for configurable links by using bound actions. These bound actions enable you to create, update, and delete multiple configurable link instances in a single request, improving efficiency when managing relationships across multiple objects.
Bound Actions for Bulk Operations
Multi-object operations are implemented using bound actions on configurablelinkable entities. These actions are bound to RoleA entity types and are available on base entity types (for example, Part). A separate bound action is defined for each configurable link type and operation.
Examples of bound actions include:
• CreateConfigurableDescribeLinks
• UpdateConfigurableDescribeLinks
• DeleteConfigurableDescribeLinks
Payload Structure for Multi-Object Operations
The request payload for multi-object operations contains a collection of configurable link instances. Each configurable link entry can include:
• The link ID (for update and delete operations)
• The @odata.type to specify the link subtype
• RoleA and RoleB references for a create operation
• Soft attributes defined on the link
Transaction Behavior
Multi-object operations are executed as a single transaction. If any operation in the request fails, the entire transaction is rolled back, and no changes are committed.
Navigation Properties for ConfigurableLink Types
Navigation properties are available to navigate between configurable link entities and their RoleA and RoleB object:
• From the link to RoleA
• From the link to RoleB
In addition, RoleA or RoleB entity types that inherit configurablelinkable have generated navigation properties that enable navigation between the RoleA or RoleB entity and the configurable link.
The navigation properties defined between configurable link entities and their RoleA and RoleB objects support read, create, update, and delete operations on configurable link instances, depending on the link type and access controls.
Validation Rules
The following validation rules apply when creating and managing configurable links:
• If either role belongs to a project, link creation is forbidden.
• If RoleA belongs to a workspace, link creation is forbidden.
• All CRUD operations on links require READ access on both RoleA and RoleB.
• For access‑controlled links (Configurable Revision Link and Configurable Masters Link), the ACLs defined on the link types apply.
The same validation rules and access control checks apply to multi-object operations.
|
|
The entities that support configurable links are configurablelinkable by default.
|
Navigation Properties for the ConfigurableDescribeLink Entity
The following are some of the key navigation properties for the ConfigurableDescribeLink entity:
• DescribedBy—From a ConfigurableDescribeLink entity to its RoleA object. Retrieves the Windchill entity that acts as the source (RoleA) of the describe link.
• Describes—From a ConfigurableDescribeLink entity to its RoleB object. Retrieves the Windchill entity that acts as the target (RoleB) of the describe link.
In addition to read operations, navigation properties between RoleA and RoleB entities and ConfigurableDescribeLink also support create, update, and delete operations on configurable describe link instances, subject to access controls and validation rules.
Navigation Property for the ConfigurableReferenceLink Entity
The following are some of the key navigation properties for the ConfigurableReferenceLink entity:
• References—From a ConfigurableReferenceLink entity to its RoleB object. Retrieves the Windchill entity that acts as the target of the reference (typically a master object, such as a part).
• ReferencedBy—From a ConfigurableReferenceLink entity to its RoleA object. Retrieves the Windchill entity that acts as the source of the reference (typically a versioned object, such as a document).
In addition to read operations, navigation properties between RoleA and RoleB entities and ConfigurableReferenceLink also support create, update, and delete operations on configurable reference link instances, subject to access controls and validation rules.
Navigation Properties for the ConfigurableMastersLinks Entity
The following are some of the key navigation properties for the ConfigurableMastersLink entity:
• Traces—From a ConfigurableMastersLink entity to its RoleB object. Retrieves the Windchill entity that acts as the target of the master-to-master relationship.
• TracedBy—From a ConfigurableMastersLink entity to its RoleA object. Retrieves the Windchill entity that acts as the source of the master-to-master relationship.
In addition to read operations, navigation properties between RoleA and RoleB entities and ConfigurableMastersLink also support create, update, and delete operations on configurable master link instances, subject to access controls and validation rules.
Navigation Properties for the ConfigurableRevisionLink Entity
The following are some of the key navigation properties for the ConfigurableRevisionLink entity:
• RevisedBy—From a ConfigurableRevisionLink entity to its RoleA object. Retrieves the Windchill entity that acts as the source (RoleA) of the revision link.
• Revises—From a ConfigurableRevisionLink entity to its RoleB object. Retrieves the Windchill entity that acts as the target (RoleB) of the revision link.
In addition to read operations, navigation properties between RoleA and RoleB entities and ConfigurableRevisionLink also support create, update, and delete operations on configurable revision link instances, subject to access controls and validation rules.
Refer to the domain EDM for a complete list of navigation properties.
Navigation Properties Generated by Configurablelinkable Entities
Entities that inherit the configurablelinkable delegate automatically gain navigation properties for applicable configurable link types based on relationship constraints. The naming convention for these navigation properties is <Role><LinkName>:
For example, consider a CustomConfigurableDescribeLink with the following roles:
• RoleA: Part, Document
• RoleB: Document
In this case:
• Part has a navigation property to CustomConfigurableDescribeLink:
DescribedByCustomConfigurableDescribeLink
• Document has two navigation properties to CustomConfigurableDescribeLink:
◦ DescribedByCustomConfigurableDescribeLink
◦ DescribesCustomConfigurableDescribeLink
The navigation properties generated on configurablelinkable entities support read, create, update, and delete operations on configurable link instances, subject to link type behavior, access controls, and validation rules.