Creating an Entity

Creating an Entity

To create new entities, ODataListBinding#create uses the list binding's update group ID as group ID. For more information how this group ID is determined, see the documentation for the binding-specific parameter $$updateGroupID of ODataModel#bindList.

A newly created entity can be inserted at the start or at the end of the list. This new entity is transient until it is successfully submitted, see Context#isTransient. The initial data for the created entity can be supplied via the parameter oInitialData and modified via property bindings or Context#setProperty. Properties that are not part of the initial data show the default value from the service metadata on the UI, but they are not sent to the server. If there is no default value, null is used instead, even if the property is not nullable. Updates for the transient entity are collected and added to the POST request which creates the entity on the server. The initial data may contain instance annotations.

Inserting an entity at the end of the list is done via the bAtEnd parameter in the create call. This is only possible, if the list's length has been requested via the system query option $count.

To delete transient entities, use Context#delete. Transient entities are also deleted when you reset the changes for the list binding on which the entity has been created, see ODataListBinding#resetChanges and ODataModel#resetChanges. The promise returned by Context#created is rejected in all cases where the created entity is deleted before it is created in the backend. As long as the list binding has a transient entity, ODataListBinding#hasPendingChanges returns true and the following methods of ODataListBinding raise an error: refresh, filter, and sort. The deletion of another entity of the same list binding is possible.

If you have called ODataListBinding#create on a list binding where the update group ID has SubmitMode.API and the creation of the entity on the server fails, the creation is repeated with the next call of submitBatch for this group. If the update group ID has SubmitMode.Auto or SubmitMode.Direct and the creation fails, the creation is repeated automatically with the next update for the entity. submitBatch can also be used for update group IDs with SubmitMode.Auto to repeat, independently of an update. The error returned by the server is passed to the MessageManager and the promise you get via Context.created is not rejected. Each time the data for the created entity is sent to the server, a Context.createSent event is fired. Each time the client receives a response for the creation, a Context.creatCompleted event is fired, independent of whether the creation was successful, or not.

If you have called ODataListBinding#create on a list binding with an application group ID, and the creation of the entity on the server fails, the creation is repeated with the next call of ODataModel#submitBatch for this group. If the update group ID is $auto or $direct, and the creation fails, the creation is repeated automatically with the next update for the entity. The error is passed to the MessageManager and the promise you get via Context#created is not rejected. Each time the data for the created entity is sent to the server, a createSent event is fired. Each time the client receives a response for the creation, a createCompleted event is fired, independent of whether the creation was successful, or not.

// suppose this list binding has no own update group; it uses the model's update group instead (an application group)
...
        onCreateSalesOrder : function (oEvent) {
            var oContext = this.getView().byId("SalesOrders").getBinding("items")
                    .create({
                        "Note" : "My new Sales Order",
                        "NoteLanguage" : "E",
                        "BuyerID" : "0100000000",
                        "CurrencyCode" : "EUR"
                    });
 
            // Note: This promise fails only if the transient entity is deleted
            oContext.created().then(function () {
                    // sales order successfully created
                }, function (oError) {
                    // handle rejection of entity creation; if oError.canceled === true then the transient entity has been deleted 
                });
        },
 
        onDeleteSalesOrder : function () {
            var oSalesOrderContext = this.getView().byId("SalesOrders").getSelectedItem().getBindingContext();
 
            oSalesOrderContext.delete("$auto").then(function () {
                    // sales order successfully deleted
               }, function (oError) {
                    // do error handling
               });
        },
 
        onSaveSalesOrder : function () {
            var oView = this.getView();
 
            function resetBusy() {
                oView.setBusy(false);
            }
 
            // lock UI until submitBatch is resolved, to prevent errors caused by updates while submitBatch is pending
            oView.setBusy(true);
             
            oView.getModel().submitBatch(oView.getModel().getUpdateGroupId()).then(resetBusy, resetBusy);
        },
...

The promise returned by Context#created is resolved when the entity represented by this context has been created in the backend. Once the promise is resolved, Context#getPath returns a path including the key predicate of the new entity. For returning the path including the key predicates, all key properties need to be available.