4.8.1.2.5. Committing New and Modified Instances, Removal

The commit function enables performing operations on objects passed to it and returning their new state. The format of the result depends on format (JSON or XML) used for the request (the Content-Type header).

JSON format

application/json should be used as the value of the Content-Type header.

Creating a Customer entity with an automatically generated identifier:

{
  "commitInstances": [
    {
      "id": "NEW-sales$Customer",
      "name": "Lawrence",
      "email": "lawrence@mail.com"
    }
  ]
}

Creating a Customer entity with a specified identifier:

{
  "commitInstances": [
    {
      "id": "NEW-sales$Customer-b32a6412-d4d9-11e2-a20b-87b22b1460c7",
      "name": "Bradley",
      "email": "bradley@mail.com"
    }
  ]
}

Creating the Order entity, specifying a link to a new Customer entity and filling the Customer entity with attributes:

{
  "commitInstances": [
    {
      "id": "NEW-sales$Order",
      "amount": 15,
      "customer": {
        "id": "NEW-sales$Customer-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff"
      }
    },
    {
      "id": "sales$Customer-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff",
      "name": "Fletcher",
      "email": "fletcher@mail.com"
    }
  ]
}

Changing two Customer entities simultaneously:

{
  "commitInstances": [
    {
      "id": "sales$Customer-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff",
      "email": "fletcher@mail.com"
    },
    {
      "id": "sales$Customer-32261b09-b7f7-4b8c-88cc-6dee6fa8e6ab",
      "email": "lawrence@mail.com"
    }
  ]
}

Removing the Customer entity with soft deletion support:

{
  "removeInstances": [
    {
      "id": "sales$Customer-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff"
    }
  ],
  "softDeletion": "true"
}

  • The commitInstances array contains created and modified entities.

    • When creating an entity, id or NEW-<entityName> should be specified as the value of the NEW-<entityName>-<uuid> field.

    • When changing an entity, <entityName>-<uuid> should be specified as the value of the id field.

    • Next, attribute names and values for created or modified entity should be provided in the list of elements, separated by commas.

      If any attribute should be set to null while editing the entity, you must specify the view that includes this attribute, in the identifier. For example:

      {
  "commitInstances": [
    {
      "id": "sales$Customer-b32a6412-d4d9-11e2-a20b-87b22b1460c7-customer-edit",
      "name": "John Doe",
      "channel": null
    }
  ]
}

      Here, the customer-edit view must contain the channel attribute, otherwise the value will not change.

  • The removeInstances array contains removed entities. When removing an entity, you must specify the value of the id field. Before deletion, merge() will be executed for the provided object, which enables checking if the version of the removed object has changed.

  • The softDeletion field controls soft deletion mode.

The function is called by a POST request to {host:port}/app-portal/api/commit?s=<sessionId>. JSON is passed in the request body. The function returns a JSON objects array. For example, the following JSON objects array will be returned when the email field of the Customer entity is changed:

  [
    {"id":"sales$Customer-32261b09-b7f7-4b8c-88cc-6dee6fa8e6ab",
      "createTs":"2013-06-14T14:07:15.040",
      "createdBy":"admin",
      "deleteTs":null,
      "deletedBy":null,
      "email":"fletcher@mail.com",
      "name":"Fletcher",
      "updateTs":"2013-06-14T15:07:03.463",
      "updatedBy":"admin",
      "version":"3"
    }
  ]
XML format

text/xml should be used as the value of Content-Type header.

XML format example:

<CommitRequest>
    <commitInstances>
        <instance id="sales$Order-9873c8a8-d4e7-11e2-85c0-33423bc08c84">
            <field name="date">2015-01-30</field>
            <field name="amount">3500.00</field>
            <reference name="customer" id="sales$Customer-32261b09-b7f7-4b8c-88cc-6dee6fa8e6ab"/>
        </instance>
    </commitInstances>
    <removeInstances>
        <instance id="sales$Customer-d67c10f0-4d28-4904-afca-4bc45654985d"/>
    </removeInstances>
    <softDeletion>true</softDeletion>
</CommitRequest>

XML document fields semantics is defined in http://schemas.haulmont.com/cuba/6.4/restapi-commit-v2.xsd scheme.

In case of an XML request, fields are set to null with the help of the null="true" attribute. In addition to that, the identifier must contain the view, which contains the attribute. For example:

<CommitRequest>
    <commitInstances>
        <instance id="Order-9873c8a8-d4e7-11e2-85c0-33423bc08c84">
            <field name="amount" null="true"/>
            <reference name="customer" null="true"/>
        </instance>
    </commitInstances>
</CommitRequest>

The function is called with a POST request to {host:port}/app-portal/api/commit?s=<sessionId>. XML is passed in the request body. The request returns array of XML objects similar to the one below:

<instances>
    <instance ...>
    <instance ...>
</instances>

The schema containing the description of the function call result is located at http://schemas.haulmont.com/cuba/6.4/restapi-instance-v2.xsd