Operations

In OData, operations are specified as HTTP methods. Any Aras Innovator action that cannot be specified as an HTTP method is passed using the custom @aras.action annotation in the request body. Actions are prepended with the action namespace to avoid conflicts with item types and property names. The actions use the POST HTTP method.

Table 4: HTTP Methods

The following example shows how the action can be used:

PATCH http://host/server/odata/Part(‘0486…23BC’)

Prefer: return=minimal

{

"@aras.action": “edit”,

“item_number": “P-025"

}

Response:

HTTP/1.1 204 No Content

Location: http://host/server/odata/Part(‘0486…23BC’)

If the action is successful, all data modification operations except DELETE return a modified item representation if the client specified return=representation in Prefer header. In a case where the client specified return=minimal, the OData service returns the 204 No Content status code.

The OData specification doesn’t define service behavior in case the return preference is omitted. In order to be consistent with Aras Innovator, the OData service uses return=representation as the default.

The response’s Location header must point to either a created or modified item.

The clientmust senda POST request to the collection URL tocreateanitem.The clientcanalso callacreate or merge action.TheRequest body mustcontainasingle itemcontainingalltherequired properties. IftheHTTP Prefer header is set to return=minimal intherequest,theOData service returns a204 No Content statuscode. Otherwise,theservice returns a201 Created status code along withtheitem’sproperties:

POST http://host/server/odata/Part

{

“item_number": “P-01"

}

Response:

HTTP/1.1 201 Created

Location: http://host/server/odata/Part(‘0486…23BC’)

{

"@odata.context": “http://host/server/odata/$metadata#Part/$entity”,

“id": “0486…23BC”,

“item_number": “P-01",

… other Part item properties

}

The client can create an item referenced by an item property in a single request (in OData,this is referred to as a deep insert):

POST http://host/server/odata/Action

Prefer: return=minimal

{

“name": “New Action”,

“method":

{

“name": “NewMethod”,

“method_type": “C#",

“method_text": "…"

}

}

Response:

HTTP/1.1 204 No Content

Location: http://host/server/odata/Action(‘01AA…FF3D’)

The client can also create relationships between items:

POST http://host/server/odata/Part

Prefer: return=minimal

{

“item_number": “P-01",

“Part_CAD": [{

“related_id":

{

“item_number": “CAD-01"

}

}]

}

Response:

HTTP/1.1 204 No Content

Location: http://host/server/odata/Part(‘0486…23BC’)

The client can use @odata.bind annotation to add a reference to an existing item:

POST http://host/server/odata/Part

Prefer: return=minimal

{

“item_number": “P-01",

“Part_CAD": [{

“related_id@odata.bind": “CAD(‘01AA…FF3D’)”

}]

}

Response:

HTTP/1.1 204 No Content

Location: http://host/server/odata/Part(‘0486…23BC’)

The client can send a POST request to a relationship property to add a new relationship item to an existing item:

POST http://host/server/odata/Part(‘C542F…EF6B’)/Part_CAD

Prefer: return=minimal

{

“related_id@odata.bind": “CAD(‘01AA…FF3D’)”

}

Response:

HTTP/1.1 204 No Content

Location: http://host/server/odata/Part(‘C542F…EF6B’)

If the Part item type is versionable, the POST request creates a new item version.

The client can also create a new relationship along with a new related item in “Innovator style”. In this case a new item version is not created:

POST http://host/server/odata/Part_CAD

Prefer: return=minimal

{

“source_id@odata.bind": “Part(‘01AA…FF3D’)”

“related_id":

{

“item_number": “CAD-01"

}

}

Response:

HTTP/1.1 204 No Content

Location: http://host/server/odata/Part_CAD(‘C542F…EF6B’)

To update an existing item the client sends a PATCH request to the specific item URL. The request body must contain a single item with updatable properties:

PATCH http://host/server/odata/Part(‘01AA…FF3D’)

{

“item_number": “P-100",

}

Response:

HTTP/1.1 200 OK

Location: http://host/server/odata/Part(‘01AA…FF3D’)

{

"@odata.context": “http://host/server/odata/$metadata#Part/$entity”,

“id": “01AA…FF3D”,

“item_number": “P-01",

… other Part item properties

}

The client can also include edit or update actions in the PATCH request for data modification:

POST http://host/server/odata/Part(‘01AA112937924D5383FB4A101B2AFF3D’)

Prefer: return=minimal

{

"@aras.action": “update”,

“item_number": “P-100"

}

Response:

HTTP/1.1 204 No Content

Location: http://host/server/odata/Part(‘01AA…FF3D’)

In order to specify a value for a simple property, the client must send a PUT request to the corresponding property URL:

PUT http://host/server/odata/Part(‘01AA112937924D5383FB4A101B2AFF3D’)/item_number

Prefer: return=minimal

{

“value": “P-001"

}

Response:

HTTP/1.1 204 No Content

Location: http://host/server/odata/Part(‘01AA…FF3D’)/item_number

The client can also send a PUT request to the $value endpoint of a simple property where the body of the request contains a raw property value:

PUT http://host/server/odata/Part(‘01AA112937924D5383FB4A101B2AFF3D’)/item_number/$value

Prefer: return=minimal

P-001

Response:

HTTP/1.1 204 No Content

Location: http://host/server/odata/Part(‘01AA…FF3D’)/item_number/$value

In order to set a value for an Item property, the client must send a PUT request to the Item property reference:

PUT http://host/server/odata/Part(‘01AA112937924D5383FB4A101B2AFF3D’)/owned_by_id/$ref

Prefer: return=minimal

{

"@odata.id": “http://host/server/odata/User(‘C542FC153AE647A59CD6F6967295EF6B’)”

}

Response:

HTTP/1.1 204 No Content

Location: http://host/server/odata/Part(‘01AA…FF3D’)

Update actions can only modify one item at time.

In order to perform an upsert operation, the client should send a PATCH request to a specific entry and include an HTTP header If-Match with the value “*” in the request. It will be translated to AML using the merge action:

PATCH http://host/server/odata/Part(‘01AA…FF3D’)

If-Match: *

{

“item_number": “P-100",

}

Response:

HTTP/1.1 200 OK

Location: http://host/server/odata/Part(‘01AA…FF3D’)

{

"@odata.context": “http://host/server/odata/$metadata#Part/$entity”,

“id": “01AA…FF3D”,

“item_number": “P-01",

… other Part item properties

}

In order to delete an existing item the client must send a DELETE request to the specific item URL:

DELETE http://host/server/odata/Part(‘01AA112937924D5383FB4A101B2AFF3D’)

Response:

HTTP/1.1 204 No Content

The client uses the @aras.action=purge annotation within the body of the query to delete only one version of the item:

DELETE http://host/server/odata/Part(‘01AA112937924D5383FB4A101B2AFF3D’)

Prefer: return=minimal

{

"@aras.action": “purge”

}

Response:

HTTP/1.1 204 No Content

To remove a relationship, the client sends a DELETE request to the $ref URL of the corresponding relationship property, passing the $id query string option:

DELETE http://host/server/odata/Part(‘01AA…FF3D’)/Part_CAD/$ref?$id=Part_CAD(‘B9D7…606F’)

Response:

HTTP/1.1 204 No Content

To clear an item property, the client sends a DELETE request to the $ref URL for the corresponding property. The Purge action cannot be used for this request:

DELETE http://host/server/odata/Part(‘01AA112937924D5383FB4A101B2AFF3D’)/owned_by_id/$ref

Response:

HTTP/1.1 204 No Content

A Delete action can only remove one item at time.

The Aras Innovator OData interface only supports get and delete operations for File items. You must use the Vault OData interface to perform a Create operation. The Update operation is not supported.

In OData, batching enables developers to bundle multiple requests into a single call to the $batch endpoint (see OData documentation). A batch request is represented as a Multipart MIME message, a standard format allowing the representation of multiple parts, each of which may have a different content type, within a single request.

Batch requests are submitted as a single HTTP POST request to the $batch endpoint of a Web Service. Any requests nested in a batch are executed sequentially and synchronously.

This section describes the headers for an HTTP POST request to the $batch endpoint.

• Content-Type: Required. This header must have the multipart/mixed value and a boundary specification as defined in the Batch Request Body section (see an example below).
  

  

  

• OData-Version: Optional. If using this header, set the value to 4.0.
• Prefer: Optional. By default, the CWS engine stops processing a batch request when any of the nested requests return an error. To continue processing the batch in case of an error in a nested request, include the Prefer header with the value odata.continue-on-error.

The body of a batch request comprises a series of individual requests and Change Sets, each represented as a distinct MIME part (i.e., separated by the boundary defined in the Content-Type header).

An individual request in the context of a batch request can be

• Data request;
• Data Modification request;
• Action invocation request.

A MIME part representing an individual request must include a Content-Type header with the value application/http and should contain a Content-Transfer-Encoding header with the value binary.

CWS supports three Request-URI formats of HTTP requests serialized within MIME part bodies:

• Absolute URI with schema, host, port, and absolute resource path
  
  • The absolute URI of each request in a batch must be the same as the URI of the source batch request.
• Absolute resource path and separate Host header
• Resource path relative to the batch request URI

The following sample batch request demonstrates each of these formats.

A Change Set is an atomic unit of work consisting of an unordered group of one or more Data Modification requests or Action invocation requests.

All Change Sets must meet the following requirements:

• Change Sets may not contain any GET requests or other Change Sets.
• The order of requests within a Change Set is significant; the requests within a Change Set are processed sequentially.
• If one request within a Change Set fails, then all requests in the Change Set are rolled back.
• Each Change Set must be a multipart MIME document with one part for each operation that makes up the Change Set.
• Each part representing an operation in the Change Set must include the same headers (Content-Type and Content-Transfer-Encoding) and associated values previously described for operations
  

  

  

• Each request within a Change Set must specify a Content-ID header with a value unique within the batch request.
• Entities created by an Insert request within a Change Set can be referenced by subsequent requests within the same Change Set in places where a resource path to an existing entity can be specified. The temporary resource path for a newly inserted entity is the value of the Content-ID header prefixed with a $ character. Examples of correct and wrong Change Set requests are below.
  

  

  

Requests within a batch are evaluated according to the same semantics used when processing individual requests. The sample batch request above generated the following response.

--batch_abcdeff8-fc75-4b56-8c71-56071383e77b

Content-Type: application/http

 

HTTP/1.1 200 OK

OData-Version:4.0

Content-Type:application/json;odata.metadata=minimal;IEEE754Compatible=false

 

{

  "@odata.context": "http://{{host}}/{{alias}}/Server/odata/$metadata#Part",

  "value": []

}

--batch_abcdeff8-fc75-4b56-8c71-56071383e77b

Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41ac-a9f8-9357efbbd

 

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd

Content-Type: application/http

Content-ID: 1

 

HTTP/1.1 201 Created

Preference-Applied:return=representation

Location:http://{{host}}/{{alias}}/Server/odata/Part('01AA112937924D5383FB4A101B2AFF3E')

OData-Version:4.0

Content-Type:application/json;odata.metadata=minimal;IEEE754Compatible=false

 

{

  "@odata.context": "http://{{host}}/{{alias}}/Server/odata/$metadata#Part/$entity",

  "id": "01AA112937924D5383FB4A101B2AFF3E",

  "major_rev": "A",

  "name": "Part-01",

  "item_number": "Part-01"

}

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd

Content-Type: application/http

Content-ID: 2

 

HTTP/1.1 201 Created

Preference-Applied:return=representation

Location:http://{{host}}/{{alias}}/Server/odata/Part('00BB112937924D5383FB4A101B2AFF56')

OData-Version:4.0

Content-Type:application/json;odata.metadata=minimal;IEEE754Compatible=false

 

{

  "@odata.context": "http://{{host}}/{{alias}}/Server/odata/$metadata#Part/$entity",

  "id": "00BB112937924D5383FB4A101B2AFF56",

  "major_rev": "A",

  "name": "Part-00",

  "item_number": "Part-00",

  "Part_BOM": [

    {

      "id": "00E01E12F3004B3283F3C88B9349E4A0",

      "sort_order": 128

    }

  ]

}

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd

Content-Type: application/http

Content-ID: 3

 

HTTP/1.1 204 NoContent

OData-Version:4.0

Content-Type:text/plain

 

 

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd--

--batch_abcdeff8-fc75-4b56-8c71-56071383e77b

Content-Type: application/http

 

HTTP/1.1 204 NoContent

OData-Version:4.0

Content-Type:text/plain

 

 

--batch_abcdeff8-fc75-4b56-8c71-56071383e77b--