PTC Annotations
The OData protocol supports specifying elements in EDM with custom annotations that provide additional information to the clients. The following annotations are available in Windchill REST Services:
• Core.Description
• PTC.Operations
• PTC.MultiOperations
• PTC.ReadOnly
• PTC.SecurityLabel
• PTC.MultiValueSecurityLabel
• PTC.CustomSecurityLabel
• PTC.UpdateableViaAction
• Org.OData.Capabilities.V1.SortRestrictions
• PTC.NonSortable
• PTC.Capability
• PTC.Capabilities
• PTC.ClassificationNameSpace
• PTC.MultipleAliasAttributeValues
• PTC.MultipleComplexAliasAttributeValues
• PTC.MultipleCalculatedAttributeValues and PTC.MultipleComplexCalculatedAttributeValues
Core.Description
This annotation is available on all entity types. It describes the entity.
<Annotation Term="Core.Description">
<String>Some description</String>
</Annotation>
PTC.Operations
This annotation specifies the list of supported CRUD operations for entities. In the example below, the annotation is applied to the Part entity in the PTC Product Management domain:
The annotation indicates that the framework supports reading, creating, updating, and deleting parts.
|
|
The entities that support the update operation, the UpdateCommonProperties action is generated in the EDM.
|
PTC.MultiOperations
This annotation is available on an entity type. It specifies the list of CRUD operations for which actions are available for multiple objects. For example, if CREATE operation is listed in the annotation for a Part entity type, then a bound action CreateParts is available for the Part entity.
<Annotation Term="PTC.MultiOperations">
<String>CREATE,UPDATE,DELETE</String>
</Annotation>
PTC.ReadOnly
This annotation indicates entity properties that are read-only. In the example below, an annotation from the EDM of the PTC Product Management domain is shown:
The annotation indicates that the property State on the Part entity is read-only.
PTC.SecurityLabel
This annotation indicates security labels. In the example below, an annotation from the EDM of the PTC Product Management domain is shown.
PTC.MultiValueSecurityLabel
This annotation indicates the security label property that allows setting multiple values. In the example below, an annotation from the EDM of the PTC Product Management domain is shown.
PTC.CustomSecurityLabel
This annotation indicates the security label property that is defined as custom security label. In the example below, an annotation from the EDM of the PTC Product Management domain is shown.
PTC.UpdateableViaAction
This annotation indicates that you cannot update the property using a PATCH request. You can modify the property using the UpdateCommonProperties action. In the example below, an annotation from the EDM of the PTC Product Management domain is shown:
Master soft attributes can now be updated using the UpdateCommonProperties bound action. Updating master IBAs through the action does not create a new iteration. To update a master soft attribute, it must have an equivalent alias attribute defined on the versioned object type. For example, with an IBA myPartMasterAttr on WTPartMaster, you must also have an alias on WTPart myAliasToPartMasterAttr with the mapping masterReference^wt.part.WTPartMaster~myPartMasterAttr. In the EDM, these alias attributes for master IBAs now have the annotation PTC.UpdateableViaAction to indicate they can be updated using the UpdateCommonProperties bound action.
Windchill access controls still apply, the user performing the action must have the right permissions on the versioned. For instance, to update an IBA, a user must have MODIFY permission and to update an object’s number a user must have MODIFY_IDENTITY.
Below is an example request:
POST /Windchill/servlet/odata/v6/ProdMgmt/Parts('OR:wt.part.WTPart:2506969')/PTC.ProdMgmt.UpdateCommonProperties
CSRF_NONCE: <nonce>
Content-Type: application/json
{
"Updates":{
"MyAliasToPartMasterAttr":["Updated String 1"],
"DefaultTraceCode":{
"Value":"w"
},
"Name":"New Name",
"EndItem":false
}
}
It is still possible to update master IBAs through a PATCH request on a working copy (existing behavior).
Org.OData.Capabilities.V1.SortRestrictions
This annotation is available on an entity set. It specifies the properties of an entity set that you cannot use for sorting the entity set.
PTC.NonSortable
This annotation is deprecated. Use the annotation Org.OData.Capabilities.V1.SortRestrictions instead. The properties marked as nonsortable are shown in the Org.OData.Capabilities.V1.SortRestrictions annotation.
PTC.Capability
This annotation is available on an entity type. It designates an entity type that implements a specific capability. In the following example, the annotation shows the Notifiable capability, which indicates that you can subscribe to the entity type and the instances of the entity type using webhooks.
<Annotation Term="PTC.Capability">
<String>Notifiable</String>
</Annotation>
|
|
PTC.Capability is deprecated in WRS 2.2. Use PTC.Capabilities instead.
|
PTC.Capabilities
This annotation is available on entity types that implement specific capabilities. This annotation can have multiple string values separated by commas. In the following example for the Change Management domain, the annotation indicates that the entity has the capabilities —Notifiable and Reservable. The Notifiable capability indicates that you can subscribe to the entity type and the instances of the entity type using webhooks. The Reservable capability denotes that the entity can be reserved while it is being accessed.
<Annotation Term="PTC.Capability">
<String>Notifiable,Reservable</String>
</Annotation>
PTC.ClassificationNameSpace
This annotation is available on a property of type PTC.ClassificationInfo. Clients can use the value from the annotation to specify the clfStructureNameSpace property while classifying a part.
<Annotation Term="PTC.ClassificationNameSpace">
<String>com.ptc.csm.default_clf_namespace</String>
</Annotation>
PTC.MultipleAliasAttributeValues
This instance annotation is only added for an alias attribute that resolves to multiple values and those multiple values are displayed as a value of the annotation. The value is displayed with the multiple values delimited by a configurable delimiter. The delimiter is set to pipe ( | ) by default. When the annotation is added, the value of the existing alias attribute is set to null.
|
|
• As of WRS 2.6, this annotation is no longer used in new domain versions (entities that inherits softAttributable version 5 or greater). The alias attribute type is always represented as Collection. The values are directly available on the property and there is no need to check the instance-based annotation such as PTC.MultipleAliasAttributeValues and PTC.MultipleCalculatedAttributeValues.
• The annotation is not added for an alias attribute that resolves to a single value.
• The multipleValuesInStringDelimiter property in the xconf file at codebase/com/ptc/odata/windchill/wrs.properties.xconf sets the delimiter.
• This property was previously in the odata.properties file at codebase/com/ptc/odata/core and has been moved to codebase/com/ptc/odata/windchill/wrs.properties.xconf starting WRS 2.6.
|
The example below shows the annotations for different types of alias attributes such as String, Boolean, Date, Integer, and Enum each resolving to multiple values. The value of the annotation added for each alias attribute is displayed with respective multiple values separated by the | delimiter and the value of the corresponding alias attribute is displayed as null.
The example also shows a String type alias attribute with a single value for which an annotation is not added. The value of the alias attribute remains unchanged.
{
"AliasAttribute": "testaliasattribute",
"AliasAttribute1": null,
"AliasAttribute1@PTC.MultipleAliasAttributeValues": "PTC Corporate Framework Criteria|Screenshot 2020-10-13 092049",
"AliasAttribute2": null,
"AliasAttribute2@PTC.MultipleAliasAttributeValues": "false|true",
"AliasAttribute3@odata.type": "#DateTimeOffset",
"AliasAttribute3": null,
"AliasAttribute3@PTC.MultipleAliasAttributeValues": "2020-10-20T13:33:07-05:00|2020-10-20T13:33:07-05:00|2020-10-20T13:36:26-05:00|2020-10-20T13:36:26-05:00",
"AliasAttribute4@odata.type": "#Int64",
"AliasAttribute4": null,
"AliasAttribute4@PTC.MultipleAliasAttributeValues": "1000|1000|400|400",
"AliasAttribute5": null,
"AliasAttribute5@PTC.MultipleAliasAttributeValues": "yes|no|na"
}
PTC.MultipleComplexAliasAttributeValues
This instance annotation is added for an alias attribute that resolves to multiple complex values. The multiple values are displayed as the value of the annotation. The value is an array of a complex type of the alias attribute. The following examples show the alias attributes of the types PTC.QuantityOfMeasure and PTC.Hyperlink:
• PartAliasAttr1 is configured as an alias attribute of type PTC.QuantityOfMeasure that resolves to multiple values
• PartAliasAttr2 is configured as an alias attribute of type PTC.Hyperlink that resolves to multiple values
PartAliasAttr1@PTC.MultipleComplexAliasAttributeValues: [
{
"@odata.type": "#null",
Value@odata.type: "#Double",
"Value": 1.0,
Unit@odata.type: "#String",
"Unit": "m/s**2",
Precision@odata.type: "#Int64",
"Precision": -1,
Display@odata.type: "#String",
"Display": "1 m/s**2"
},
{
"@odata.type": "#null",
Value@odata.type: "#Double",
"Value": 2.0,
Unit@odata.type: "#String",
"Unit": "m/s**2",
Precision@odata.type: "#Int64",
"Precision": -1,
Display@odata.type: "#String",
"Display": "2 m/s**2"
}
],
"PartAliasAttr1": null,
PartAliasAttr2@PTC.MultipleComplexAliasAttributeValues: [
{
"@odata.type": "#null",
URL@odata.type: "#String",
"URL": www.amazon.com,
Label@odata.type: "#String",
"Label": "amazon"
},
{
"@odata.type": "#null",
URL@odata.type: "#String",
"URL": www.google.com,
Label@odata.type: "#String",
"Label": "google"
}
],
"PartAliasAttr2": null,
PTC.MultipleCalculatedAttributeValues and PTC.MultipleComplexCalculatedAttributeValues
This instance annotation is added for calculated attribute that resolves to multiple primitive values and multiple complex values respectively. The multiple values are displayed as value of the annotation. The value is an array for complex type of the calculated attribute, else for primitive types the value is displayed as string with multiple values delimited by a configurable delimiter. The following examples show the calculated attributes of type PTC.QuantityOfMeasure:
• PartCalAttr1 configured as calculated attribute of type String that resolves to multiple String values
• PartCalAttr2 configured as calculated attribute of type PTC.QuantityOfMeasure that resolves to multiple complex values
• PartCalAttr3 configured as calculated attribute of type Int that resolves to multiple Int values
"PartAliasAttr2": null,
PartCalAttr3@PTC.MultipleCalculatedAttributeValues: "1|2|7|45",
PartCalAttr3@odata.type: "#Int64",
"PartCalAttr3": null,
PartCalcAttr1@PTC.MultipleCalculatedAttributeValues: "testattr1|testattr2",
"PartCalcAttr1": null,
PartCalcAttr2@PTC.MultipleComplexCalculatedAttributeValues: [
{
"@odata.type": "#null",
Value@odata.type: "#Double",
"Value": 22,
Unit@odata.type: "#String",
"Unit": "kg",
Precision@odata.type: "#Int64",
"Precision": -1,
Display@odata.type: "#String",
"Display": "22 kg"
},
{
"@odata.type": "#null",
Value@odata.type: "#Double",
"Value": 125,
Unit@odata.type: "#String",
"Unit": "kg",
Precision@odata.type: "#Int64",
"Precision": -1,
Display@odata.type: "#String",
"Display": "125 kg"
},
{
"@odata.type": "#null",
Value@odata.type: "#Double",
"Value": 225,
Unit@odata.type: "#String",
"Unit": "kg",
Precision@odata.type: "#Int64",
"Precision": -1,
Display@odata.type: "#String",
"Display": "225 kg"
}
],
"PartCalcAttr2": null,
