Thursday, 14 July 2016

New way to work with CustomInfo of PXLongOperation.

Hi All,

Today I want to share with you one change in Acumatica framework that may affects your development and customization. I will speak about PXLongOperation and Set/Get Custom Info methods.
Idea of PXLongOperation is quite nice - it helps developers to automatically manage background processes as as the result save a lot of time. PXLongOperation class is designed to lunch, terminate and get the result of all processings, that takes a lot of time for some calculations. Acumatica Framework automatically creates thread, ensure its stability, catch errors (if any) and than notify end users about the result of the operation.

As UI leaves separately from all server processing, you do not have any way to do direct communication from processing thread to business logic. So UI in the browser periodically generates a callbacks to server to check statuses of processing operation. If operation has been finished, you well see the result of the operation. There is also some additional logic what to do if operation has been failed or completed successfully:
  • Do we need to attach an error to some field?
  • Do we need to reread data from database? Here system will automatically call Cancel action on the graph, when operation is completed.

Some times you need to have more communications between background thread and main application code, like custom error notifications or sharing of the processing result. Especially for this task Acumatica framework has set of methods:
  • void SetCustomInfo(object info);
  • object GetCustomInfo(object key);
  • bool HasCustomInfo(object key);
  • void SetCustomInfoPersistent(object info); 
  • object GetCustomInfoPersistent(object key);
  • void RemoveCustomInfoPersistent(object key);

In Bold i have highlighted new functions in 5.3.
As a info you can pass any reference type object.
All "Get" methods require key of long operation. When you launching operation you passing this key there PXLongOperation.StartOperation(this, delegate () {}). If the key is PXGraph, than Acumatica automatically change the key to graph.UID - unique identifier of the graph. System will change it as key should be serializable.
All "Set" methods does not require key, as the key will be a thread ID where you execute your code.

The main different between 5.3 and the previous version is the logic how Acumatica removes custom info from memory after informing the user interface about the result. In previous version of Acumatica you were able just to get the result after on any further event like RowSelected, even if Cancel action was triggered.
But in the version 5.3 Cancel action will remove custom info from memory. This is requered for performance and memory optimization especially for heavy integration processes. So several points:
  • If you put any object to custom info, Acumatica will not trigger Cancel.
    • You can do it manually in your code if required.
  • To automatically trigger Cancel action your custom info class should implement IPXCustomInfo interface.
    • This interface has only one method - Complete, that will be called upon UI has found that processing operation has been completed.
    • In this method you should implement all logic that you need to do upon receiving of custom info from background process.
    • Right after calling of Complete method, system will trigger Cancel action and remove all references to info class from PXLongOperation pool. So you will not be able to get this object with GetCustomInfo() method any more.
    • On Complete action you have a reference to the Graph object where you can subscribe for some new events. Do all your validations on events.
  • If you need to store info there permanently, you should use Set(Get)CustomInfoPersistent methods.
Code example of how to map processing errors to lines in document:

Have a nice development!

No comments: