Configuring Navigation Properties
Navigation properties in OData are the reference attributes of an entity that points to another entity. By default, navigation properties are not available on an entity representation when it is accessed by an OData client. The OData client must expand these properties explicitly if they want the associated entities to be available when the entity is being accessed. Windchill REST Services reads the navigation property, which is a JSON array, from the <Entity JSON> file. Each entry in the navigations section defines one navigation property for the entity being configured. The navigation property consists of the following parameters:
• name—Name of the navigation property. Property name is always defined in camel case.
• target—OData entity set which is the target of this navigation. The entity being configured is the source entity. The entity set to which the navigation is being configured is the target entity.
• type—OData type of the target entity set.
• isCollection—Boolean which checks if the navigation to the target entity results in an entity set.
• containsTarget—Boolean which checks if the navigation property is a containment navigation property. A containment navigation property in OData enables the read URL of a navigation property to be implicitly treated as an entity set.
• immutable—Checks that the navigation property is immutable when the parameter value is set as true. The framework then allows to set the initial value of the property while creating the entity, but does not allow to update the value, thereafter.
• traversal—A traversal string for navigation between two entities. You must create alias attribute mapping. You can navigate from one Windchill object type to another using the alias attribute mapping. Search for alias attribute mapping in the
Windchill help center.
Use this parameter to apply a filter on a navigation property. This parameter is mandatory if you want to filter entity sets.
◦ Example 1: consider the Parts.json file, where traversal is defined for the Uses navigation property. In this case, you can apply the filter on the Uses navigation property to filter the Parts entity set.
{
"name": "Uses",
"target": "PartUses",
"type": "PartUse",
"isCollection": true,
"containsTarget": true,
"traversal":"usedBy@wt.part.WTPartUsageLink"
}
The following URL returns any part that has at least one usage link with find number equal to ‘10T’:
/ProdMgmt/Parts?$select=ID,Name&$filter=Uses/any(u:u/FindNumber eq '10T')
◦ Example 2: In the following example the traversal string for the Attachments navigation is set to theContentHolder@wt.content.HolderToContent~theContentItem^wt.content.ApplicationData. Use the following URL:
/DocMgmt/Documents?$filter=Attachments/any(d:contains(d/PTC.ApplicationData/Format,'<attachmentformat>'))
This URL returns all the documents that have attachments in the specified type of format.
• rbInfoForDisplayName—This property must be set to return a custom display name for a navigation property of an entity. It is defined as:
"rbInfoForDisplayName": "<rbinfo_ClassName>|<key>"
• If "Uses" NavigationProperty on Parts.json is marked as "Nullable": false. If you try to create an entity without the navigation binding for the property, an error message is returned. For example,
{
"error": {
"code": "REQUIRED_PROPERTY_MISSING",
"message": "You must give a value for the following required property: <Name of NavigationProperty>"
}
}
• required— This property specifies if the navigation property is a mandatory property. Set the parameter value as true or false. If the value is set to true, a value for the navigation property binding link is required when performing POST request to create a relationship between two existing entities. For example, to create a Uses relationship between two parts, you must provide a value for the mandatory Uses@odata.bind, as shown in the following request body:
Request URL:
POST /Windchill/servlet/odata/ProdMgmt/Parts('OR:wt.part.WTPart:2145738')/Uses
Request Body:
{
"Quantity": 2,
"Unit": {
"Value": "ea",
"Display": "each"
},
"TraceCode": {
"Value": "0",
"Display": "Lot"
},
Uses@odata.bind: "Parts('OR:wt.part.WTPart:2145730')"
}
If no value is specified for Uses@odata.bind, the request fails with the following error message:
{
"error": {
"code": "REQUIRED_PROPERTY_MISSING",
"message": "You must give a value for the following required property: Uses"
}
}