Request Translation

This section describes the following:

• OData Request URL format
• Entities and properties
• Item properties

The OData Request URL points to the requested entity/entity collection. The URL path starts from the entity set of an action/function call. The following example shows the components of the OData URL:y

Entity sets contain predefined collections of entities. In Aras Innovator each item type name represents an entity set. For example, the following request returns all items of type Part: GET: http://host/server/odata/Part Response: { "@odata.context": “http://host/server/odata/$metadata#Part”, “value": [ { “id": "…", “item_number": “P-01", … remainig Part item properties }, … remaining Part items ] } The client can request a specific item of type Part by passing the item ID in parentheses, as shown in the following example: GET http://host/server/odata/Part(‘048649CAF3F04D75928B1ECD702E23BC’) Response: { "@odata.context": “http://host/server/odata/$metadata#Part/$entity”, “id": “048649CAF3F04D75928B1ECD702E23BC ", “item_number": “P-01", … other Part item properties } The client can use the $filter attribute in the query for Part items to return a result subset:
GET
http://host/server/odata/Part?$filter=item_number eq ‘P-01’
Response:
{
"@odata.context": “http://host/server/odata/$metadata#Part”, “value": [
{
“id": "…", “item_number": “P-01", … remaining Part item properties } ]
}
For requests that return a collection, the client can append $count to the request to get the number of elements contained in the collection. Use the AML attributes pagesize=”1” and page=”1” to limit the number of items returned in the response. The number of resulting items is stored in the response’s itemmax attribute:
GET http://host/server/odata/Part/$count\
Response (value of itemmax attribute of the returned <Item> unless “no items” Fault is returned):
12
Append the property name to the resource path to request a property such as item_number, as shown here:
GET http://host/server/odata/Part(‘048649CAF3F04D75928B1ECD702E23BC’)/item_number Response:
{
"@odata.context": “http://host/server/odata/$metadata#Part/$entity/item_number”, “value": “P-01"
}

The OData service only returns the item_number property in the response. The request returns the property in the appropriate format (e.g. JSON).The client can add the $value attribute to the request to get the raw property value:
GET http://host/server/odata/Part(‘048649CAF3F04D75928B1ECD702E23BC’)/item_number/$value
Response:
P-01
This request returns the raw value of the item_number property.

An Item property contains the ID of the referenced item. When the client requests an item with an Item property, the property does not appear in the response unless its name is specified in either a $select or $expand list. If the Item property is specified in a $select list, the OData service returns the property value referencing the corresponding item. All additional attributes of the corresponding AML element appear in the response with the annotation @aras.*:
GET http://host/server/odata/Part(‘048649CAF3F04D75928B1ECD702E23BC’)?$select=created_by_id
Response:
{
"@odata.context": “http://host/server/odata/$metadata#Part(created_by_id)/$entity”, “id": “048649CAF3F04D75928B1ECD702E23BC”, “created_by_id@odata.navigationLink":"User(‘0CB01F8A2A93430B9A713F7196A85B20’)”, “created_by_id@aras.keyed_name":"Innovator Admin”, }

If the client specifies an Item property in an $expand list, the OData service returns the value of the property as a full item:
GET http://host/server/odata/Part(‘048649CAF3F04D75928B1ECD702E23BC’)?$expand=created_by_id Response: { "@odata.context": “http://host/server/odata/$metadata#Part/$entity”, “id": “048649CAF3F04D75928B1ECD702E23BC”, “created_by_id":
{
“id": “0CB01F8A2A93430B9A713F7196A85B20",
… other User item properties
},
… other Part item properties
}
The $expand and $select options can contain more than one property and can be combined in one request, as shown here:
GET http://host/server/odata/Part(‘048649CAF3F04D75928B1ECD702E23BC’)?$expand=created_by_id,Part_CAD
&$select=item_number,owned_by_id
Response:
{
"@odata.context": “http://host/server/odata/$metadata#Part(item_number, owned_by_id,created_by_id,Part_CAD)/$entity”, “id": “048649CAF3F04D75928B1ECD702E23BC”, “item_number": “P-01", “created_by_id": {
“id": “0CB01F8A2A93430B9A713F7196A85B20", … other User item properties }, “owned_by_id@odata.navigationLink":"User(‘A035BBBCCC8D40BEBED49D71E3129E6F’)”, “owned_by_id@aras.keyed_name":"Innovator User”, “Part_CAD": [ { “id": "…", … remainig Part_CAD item properties }, … remaining Part_CAD items ] }
If the client requests the Item property itself, the OData Interface returns all of the properties associated with the referenced item:
GET http://host/server/odata/Part(‘048649CAF3F04D75928B1ECD702E23BC’)/created_by_id Response:
{
"@odata.context": “http://host/server/odata/$metadata#User/$entity”,
“id": “0CB01F8A2A93430B9A713F7196A85B20",
… other User item properties
}

The client appends the relationship name to the resource path in the request:
GET
http://host/server/odata/Part(‘048649CAF3F04D75928B1ECD702E23BC’)/Part_CAD
Response:
{ "@odata.context": “http://host/server/odata/$metadata#Part_CAD”, “value": [ {
“id": "…", … remainig Part_CAD item properties }, … remaining Part_CAD items ] }
This request returns the collection of Part_CAD relationship items.

In order to request a related item, the client should request the related_id property for a specific relationship item:
GET http://host/server/odata/Part(‘0486…23BC’)/Part_CAD(‘01AA…FF3D’)/related_id
Response: {
"@odata.context": “http://host/server/odata/server/$metadata#CAD/$entity”,
“id": “B9D77528B11B4516BB244F75BE2E606F”,
“item_number": “CAD-01",
… other CAD item properties
}
The OData service only returns the related_id property.

A Request for a file property returns the File item along with the corresponding odata.media* annotations describing the file stream:
GET http://host/server/odata/Document(‘A035…9E6F’)/Document_File(‘536E…3114’)/related_id
Response:
{
"@odata.context": “http://host/server/odata/server/$metadata#File/$entity”,
"@odata.mediaContentType": “application/pdf”,
"@odata.mediaReadLink": “File(‘4792…89B0’)/$value”,
“id": “4792…89B0",
“filename": “PartDescription.pdf”,
… other File item properties
}
The OData service only returns the received File item.
In order to get the file content, the client adds the $value attribute to the resource path. In this case the OData service constructs a file URL and redirects the client to the Vault server The Vault server is selected based on the Vault priority assigned to the current user. For example, if the user accessing the Vault server is located in China and the server is also located in China, then the server is assigned a priority of 1.
GET http://host/server/odata/Document(‘A035…9E6F’)/Document_File(‘536E…3114’)/related_id/$value

When the client requests either an Item property or a collection with the PolyItem type, the OData service adds an @odata.type annotation in the response that describes the item type for each item returned by the service:
GET http://host/server/odata/Affected_Item(‘0486…23BC’)/affected_id
Response:
{
"@odata.context": “http://host/server/odata/$metadata#Affected_Item/$entity/affected_id”,
"@odata.type": "#Part”,
“id": “47921523824141E084EA4EE4C06A89B0",
… other Part item properties
}

Aras Innovator supports Extended Properties (xProperties). You need to assign an xProperty to a specific item type before you can use it. Once you assign the xproperty, it can be used by items of the same ItemType. You can also create xClasses. xProperties assigned to Parent xClasses are inherited by the child xClasses.
Users with the correct permissions can create and maintain xProperty Definitions and Classification Trees either programmatically or through the UI. End users can assign multiple xProperties to one item. They can also:

• Classify items
• Use xProperty values to search for items.

The OData Interface enables you to perform the following operations:

• Get
• Define
• Update
• Set permissions

You can use the Get operation to retrieve x-properties by using the $select option as shown in the following example: GET http://host/server/odata/Part(‘AF1A....8A88’)?$select=xp-prop1,xp-prop2

Before you can use an explicitly defined xProperty on an item, you must define it. Add an “explicit” value to the “set” attribute and add an “explicit” attribute with the value “1".
To set an xProperty to an undefined state, add the “explicit” value to the “set” attribute and add an “explicit” attribute with the value “0".

If an xProperty with a value is included in the JSON body, the “value” is automatically added to the set attribute.
PATCH
http://host/server/odata/Part(‘048649CAF3F04D75928B1ECD702E23BC’)
{
“xp-prop": “xp-prop-value”
}
Response:
HTTP/1.1 200 OK
{
"@odata.context": “http://host/server/odata/$metadata#Part/$entity”,
“id": "…",
“xp-prop": “xp-prop-value”,
… remaining Part item properties }

Users can change the permission xProperty as shown in the following example.
PATCH
http://host/server/odata/Part(‘048649CAF3F04D75928B1ECD702E23BC’)
{
“xp-prop@aras.permission_id": "…"
}
Response:
HTTP/1.1 200 OK
{
"@odata.context": “http://host/server/odata/$metadata#Part/$entity”,
“id": "…"
… remaining Part item properties
}

Item properties without “Get” permissions are returned with a null value and the “is_null” attribute is equal to “0". To provide information about these properties, "@aras.restricted” metadata is returned in the item, but will not be returned in the response. The same rules apply to xProperties.
Get: http://host/server/odata/Part(‘048649CAF3F04D75928B1ECD702E23BC’)?$select=*

Response:
{
"@odata.context": “http://host/server/odata/$metadata#Part/$entity”,
“id": "…",
“xp-prop@aras.restricted": true,
“team_id@aras.restricted": true,
… remaining Part item properties
}