Edit cache

BXNT provides an application-level transactional system called edit cache, which allows you to make edits across a session before saving them to the database or discarding them. This works as follows:

you start an edit session by setting the persistEditCache argument to true on the first request, and any consecutive requests except the last one
you receive a session identifier called partialRequestId
in any consecutive request, you can make edits or read from the edit cache by specifying the partialRequestId from the first request
at the end of the session you either save or discard the edit cache
if any partial request in the session specifies the partialRequestId but not the persistEditCache, then the request completes with the saving of the edit cache

Edit cache requests can be executed both synchronously and asynchronously.

Let us look at several examples to understand how this works in practice.

In the following query, we are creating a order with one order line, and then add one more line to the newly created order.

Query
mutation create_order($cid:Int!,
                      $cno : Int,
                      $pno1 : String,
                      $pno2 : String,
                      $ono : Int = 0)
{
  useCompany(no:$cid, persistEditCache : true)
  {
    partialRequestId
  
    order_create(values:[
      {
        customerNo : $cno
        orderLines : [
          {
            productNo : $pno1,
            quantity : 1
          }
        ]
      }
    ])
    {
      affectedRows
      items
      {
        orderNo @export(as: "ono")
        customerNo
      }
    }
  
    orderLine_create(values:[{
      orderNo : $ono,
      productNo : $pno2,
      quantity : 1
    }])
    {
      affectedRows
      items
      {
        orderNo
        lineNo
        productNo
        quantity
        priceInCurrency
      }
    }
  }
}

Result
{
  "data": {
    "useCompany": {
      "partialRequestId": "097ADD2B-C197-4AD3-B639-4FF5BB197325",
      "order_create": {
        "affectedRows": 1,
        "items": [
          {
            "orderNo": 3442,
            "customerNo": 10001
          }
        ]
      },
      "orderLine_create": {
        "affectedRows": 1,
        "items": [
          {
            "orderNo": 3442,
            "lineNo": 2,
            "productNo": "101",
            "quantity": 1,
            "priceInCurrency": 0
          }
        ]
      }
    }
  }
}

We can continue making edits using the same session ID. For instance, we can add one more line to the order:

Query
mutation create_order($cid:Int!, 
                      $reqid : String,
                      $ono : Int,
                      $pno : String)
{
  useCompany(no:$cid, partialRequestId : $reqid, persistEditCache : true)
  {
    orderLine_create(values:[{
      orderNo : $ono,
      productNo : $pno,
      quantity : 1
    }])
    {
      affectedRows
      items
      {
        orderNo
        lineNo
        productNo
        quantity
      }
    }
  }
}

When the session is completed, we can save the edits by making a request without persistEditCache argument, using the finishEditCache field with the action argument set to SAVE:

Query
mutation save_editcache($cid:Int!)
{
  useCompany(no:$cid, partialRequestId:"097ADD2B-C197-4AD3-B639-4FF5BB197325")
  {
    finishEditCache(action : SAVE)
    {
      success
    }
  }
}

If instead you want to discard the edits, you make a similar request but with the action argument set to DISCARD:

Query
mutation discard_editcache($cid:Int!)
{
  useCompany(no:$cid, partialRequestId:"097ADD2B-C197-4AD3-B639-4FF5BB197325")
  {
    finishEditCache(action : DISCARD)
    {
      success
    }
  }
}

If a request specifies the partialRequestId without setting persistEditCache to true that completes the session, saving the edits. For instance, the following query will add an order line to and order and then complete the session persisting all the changes to the database:

Query
mutation create_order($cid:Int!, 
                      $reqid : String,
                      $ono : Int,
                      $pno : String)
{
  useCompany(no:$cid, partialRequestId : $reqid)
  {
    orderLine_create(values:[{
      orderNo : $ono,
      productNo : $pno,
      quantity : 1
    }])
    {
      affectedRows
      items
      {
        orderNo
        lineNo
        productNo
        quantity
      }
    }
  }
}

If you want to discard or save an edit cache session that no longer exists, you get one of the following errors:

for discarding: “Failed to discard edit cache. The partial request ID <sessionid> was not found.”
for saving: “Failed to save edit cache. The partial request ID <sessionid> was not found.”