How to consume an OData Service with OpenUI5 / SAPUI5?

OpenUI5 is the open source version of SAPUI5. It is an UI development toolkit for HTML5. See http://openui5.org/ or https://blogs.sap.com/2013/12/11/what-is-openui5-sapui5/ for more details.

UI5 provides the sap.ui.model.odata.ODataModel. The model can be used via data binding or via the API.

The API supports synchronous and asynchronous processing. The asynchronous functions return an oRequest object that provides an abort function to abort the according request.

In addition it is possible to work directly with the model and collect changes to submit them together.

Create

oModel.create("/YourCollection", oData, {
  success: function(oCreatedEntry) { /* do something */ },
  error: function(oError) { /* do something */ }
);

Create always returns the topmost created node. If a hierarchy was created and shall be processed further, you can read it with $expand.

oModel.create("/YourCollection", oData, {
  success: function(oCreatedEntry) {
    oModel.read("/YourCollection('"
      + oCreatedEntry.ObjectID+"')/?$expand=YourChild", {
      success: function(oCompleteEntry) { /* do something */ },
      error: function(oError) { /* do something */ }
    });
  }, 
  error: function(oError) { /* do something */ }
});

The success callback is supplied with the created ROOT (e.g. Employee) node. Its ObjectID value is used to formulate a read request of the very same ROOT node (e.g. Root node of Employee BO), expanding to include the COMMON nodes (e.g. EmployeeCommon) as well. Using EmployeeRoot and EmployeeCommon it would be formulated like:

oModel.create("/EmployeeCollection", oData, {
  success: function(oCreatedEntry) {
    oModel.read("/EmployeeCollection('"
      + oCreatedEntry.ObjectID+"')/?$expand=EmployeeCommon", {
      success: function(oCompleteEntry) { /* do something */ },
      error: function(oError) { /* do something */ }
    });
  }, 
  error: function(oError) { /* do something */ }
});

An alternative would be to directly read the COMMON nodes that have the created ROOT as parent:

oModel.create("/EmployeeCollection", oData, {
  success: function(oCreatedEntry) {
    oModel.read("/EmployeeCommonCollection/?"+
      "$filter=ParentObjectID eq '"+oCreatedEntry.ObjectID+"'", {
      success: function(oChildEntry) { /* do something */ },
      error: function(oChildError) { /* do something */ }
    });
  },
  error: function(oError) { /* do something */ }
});

Retrieve

The read function can be used to retrieve multiple instances:

oModel.read("/YourCollection...", {
  success: function(oRetrievedResult) { /* do something */ },
  error: function(oError) { /* do something */ }
});

or just one

oModel.read("/YourCollection('...')", {
  success: function(oRetrievedResult) { /* do something */ },
  error: function(oError) { /* do something */ }
});

Update

There are two types of updates, MERGE and PUT:

MERGE is the more frequently used and updates only the stated properties with the new values.

oModel.update("/YourCollection('...')", oData, {
  merge: true, /* if set to true: PATCH/MERGE */
  success: function() { /* do something */ },
  error: function(oError) { /* do something */ }
});

PUT replaces the node data, sets the stated properties as given and reverts all others to there default values.

oModel.update("/YourCollection('...')", oData, {
  success: function() { /* do something */ },
  error: function(oError) { /* do something */ }
});

OpenUI5 can directly submit changes, or collect them to then submit all model changes together.

This allows you to minimize requests and model refreshes. In addition, the model has batch support to bundle operations.

As an update is a Business Object Modify, other node values or nodes might change as a consequence.

oModel.submitChanges(
  function() { /* success: do something */ },
  function(oError) { /* error: do something */ }
);

Delete

To delete an Business Object instance, we use a remove function call on the instance to delete:

oModel.remove("/YourCollection('...')", {
  success: function() { /* do something */ },
  error: function(oError) { /* do something */ }
});

Function Imports

oModel.callFunction("yourfunctionimport",
  "POST", /* or PATCH or POST or GET or DELETE */
  {"parameter1" : "value1" },
  null,
  function(oData, oResponse) { /* do something */ },
  function(oError){ /* do something */ }
);

While callFunction clearly indicates, that a Function Import is called, it is also possible to use other functions to access them as long as the used HTTP method matches.

For example, a query could be triggered with read (Method GET).

oModel.read("/your_query?firstname='John'&lastname='Doe'", {
   success: function(oQueryResult) { /* do something */ }
});

Security

OpenUI5 provides protection against cross site request forgery (CSRF) out of the box. The token is fetched and used automatically. You can get the current token with

var sToken = oModel.getSecurityToken();

You can request a new token at any time, for example before mass updates.

oModel.refreshSecurityToken(function() {
  window.alert('Successfully retrieved CSRF Token: ' 
    + oModel.oHeaders['x-csrf-token']); 
}, function() {
  window.alert('Error retrieving CSRF Token');
}, false);