Support for EDM Enum Type
The EDM enumerated type is supported by the Windchill Rest Services framework.
Declaring an EDM Enumerated Type
An enum type is defined in a separate folder named enumType which resides under the domain version folder. The folder needs to exist only when one or more enum type is defined.
Inside the enumType folder define the enumerated type configuration JSON file with the following properties as shown in this example that does not use any default values:
Example 1:
{
"name" : "SampleEnumTypeName",
"underlyingType" : "Edm.Int16",
"isFlags" : true,
"description" : "Sample enumerated type for showing how this will work",
"members" : [
{
"name" : "SampleValueOne",
"value" : "1",
"description" : "The first sample enum value"
},
{
"name" : "SampleValueTwo",
"value" : "2",
"description" : "The second sample enum value"
}
]
}
"name" : "SampleEnumTypeName",
"underlyingType" : "Edm.Int16",
"isFlags" : true,
"description" : "Sample enumerated type for showing how this will work",
"members" : [
{
"name" : "SampleValueOne",
"value" : "1",
"description" : "The first sample enum value"
},
{
"name" : "SampleValueTwo",
"value" : "2",
"description" : "The second sample enum value"
}
]
}
Enumerated Type Properties
The following enum type properties are specified in the json file:
• The underlyingType property is an option string property. If specified, it must be one of the following types: (Edm.Byte, Edm.SByte, Edm.Int16, Edm.Int32, Edm.Int64). If not specified, it defaults to Edm.Int32.
• The isFlags property is an optional boolean property for bit-wise enum. If not specified, it defaults to false for a numeric enum.
• The description property is an optional string property; if present, the framework will generate a 'core' description annotation for the enumerated type.
• The members array is required and must have one or more value member entries.
Enumerated Type Member
• The name property is a required string and must be a simple identifier and unique (ignoring case) within the enumerated type.
• The value property is optional. If the isFlags property for the type is false, either all member entries must specify an integer value conforming to the underlying type, or all entries must not specify a value attribute, and will receive a default value starting at 0 and incrementing by one for each entry.
If the isFlags property is true, each member entry must have a non-negative integer value (specifying a bit-wise flag). The underlyingType must be Edm.Byte to specify bit-wise enum.
• The description property is an optional string property; if present, the framework will generate a 'core' description annotation for the member.
The bare minimum necessary info for the example above (using all defaults) is:
Example 2:
{
"name": "SampleEnumTypeName",
"members": [
{
"name": "SampleValueOne"
},
{
"name": "SampleValueTwo"
}
]
}
"name": "SampleEnumTypeName",
"members": [
{
"name": "SampleValueOne"
},
{
"name": "SampleValueTwo"
}
]
}
EnumType Entry in the Metadata
An enumerated type that does not conform to the configuration detailed above will generate a misconfiguration error.
The framework generates an EnumType entry in the metadata for each enumerated type defined. The options above would logically map to the EnumType and Member CSDL entries. The metadata generated for the Example 1 (using no defaults) are as follows:
<EnumType Name="SampleEnumTypeName" UnderlyingType="Edm.Int16" IsFlags="true" >
<Annotation Term="Core.Description" String="Sample enumerated type for showing how this will work"/>
<Member Name="SampleValueOne" Value="1">
<Annotation Term="Core.Description" String="The first sample enum value"/>
</Member>
<Member Name="SampleValueTwo" Value="2">
<Annotation Term="Core.Description" String="The first sample enum value"/>
</Member>
</EnumType>
<Annotation Term="Core.Description" String="Sample enumerated type for showing how this will work"/>
<Member Name="SampleValueOne" Value="1">
<Annotation Term="Core.Description" String="The first sample enum value"/>
</Member>
<Member Name="SampleValueTwo" Value="2">
<Annotation Term="Core.Description" String="The first sample enum value"/>
</Member>
</EnumType>
The metadata generated for the Example 2 (using all defaults) are as follows:
<EnumType Name="SampleEnumTypeName">
<Member Name="SampleValueOne"/>
<Member Name="SampleValueTwo"/>
</EnumType>
<Member Name="SampleValueOne"/>
<Member Name="SampleValueTwo"/>
</EnumType>
Using an enumerated type
An enumerated type property can be defined by specifying the fully qualified type name. For example:
...
"name" : "SomeProperty",
"internalName" : "someProperty",
"type" : "PTC.ProdMgmt.SampleEnumTypeName", …
...
"name" : "SomeProperty",
"internalName" : "someProperty",
"type" : "PTC.ProdMgmt.SampleEnumTypeName", …
...
The value of an enumerated type property would be the enumeration member name, or a comma-separated list of the member names in the case of a flag-based enumeration. For example:
....
"SomeEnumTypeProperty" : "SampleValueOne",
"SomeFlagStyleTypeProperty" : "Read,Write",
....
"SomeEnumTypeProperty" : "SampleValueOne",
"SomeFlagStyleTypeProperty" : "Read,Write",
....
Filtering is supported on enumerated type properties. For example::
/ProdMgmt/Parts?$filter=SomeEnumTypeProperty eq PTC.ProdMgmt.SomeEnumTypeName'SampleValueOne'
Enumerated type properties also support the $orderby operation and the $expand operation.
Enumerated type properties support the $value operation. For example:
/ProdMgmt/Parts(<oid>)/SomeEnumTypeProperty/$value
Using enumerated type properties in entity modification operations is supported. For example, you can specify enum value on POST, and update enum value via PATCH.
 |
EDM enum types do not support a localized display name and should not be used for Windchill enumerations. use the EnumType complex type for Windchill enumerations.
|