View source | Discuss this page | Page history | Printable version   

Retail:Developers Guide/How-to/Add Mobile Process

How to add new mobile process and subscribe components to it



Mobile Process is a process in the client side and it's start and finish is defined by the developer. For example, calculateReceipt is a Mobile Process defined in the code which starts when the order is changed. We calculate discounts, gross, taxes... inside the process and when all ticket values are calculated we mark as finished this process.

Process Controller is an API which allow us to define Mobile Processes and subscribe components to these processes.

Bulbgraph.png   Process Controller is available starting from 18RRQ3

How it works

First of all, we need to define a Mobile Process in the ERP and then set in the code where the process starts and where finishes. Then, we need to think which components(buttons, popups, labels...) should listen what we defined previously and subscribe it into the process. Finally, we will be able to implement what we want to do when the process starts and what we want to do when the process finishes.

Process Controller, when a process starts (where developer decided) goes through the subscribed components and in order of subscription (FIFO) the API will execute the processStarted code implemented for each component in the list. When the process finishes Process Controller will do the same but executing processFinished function.

Add a Mobile Process and subscribe a component to it

There are several steps than need to be done and pay attention to the notes or suggestions.

Define a Mobile Process in the ERP

As System Administrator go to Mobile Process window and create one:

Bulbgraph.png   Starting from 19RRQ2 these options are also available in Process controller definition

Mobile Process.png

Set the start/finish of the Process

We need to define where the process starts/finishes.

Defining starting point, we will call var execution = OB.UTIL.ProcessController.start('searchKey') using the searchKey defined previously in Mobile Processes window and we will save it in a variable because its execution has a unique id to differentiate each execution of the same process.

Defining finishing point, we will call OB.UTIL.ProcessController.finish('searchKey', execution); passing the previous saved var to finish that execution.

Bulbgraph.png   The process can be asynchronous and could have many finish points (successCallback, errorCallback...). Ensure that you cover all possible finish point for processes. If we don't finish properly processes we will javascript error with the processes not finished

See below an example of the implementation:

clearWith: function (_order) {
      var execution = OB.UTIL.ProcessController.start('clearWith');
      // verify that the clearWith is not used for any other purpose than to update and fire the events of the UI receipt
      OB.UTIL.Debug.execute(function () {
        var isTheUIReceipt = this.cid === OB.MobileApp.model.receipt.cid;
        if (!isTheUIReceipt) {
          OB.error("The target of the clearWith should only be the UI receipt. Use OB.UTIL.clone instead");
      }, this);
      //Enable recalculating service relations after cloning
      this.set('isEditable', _order.get('isEditable'));
      OB.UTIL.ProcessController.finish('clearWith', execution);
Process controller scrim behavior
Bulbgraph.png   Starting from 19RRQ2 the behavior is as described below

From now on, the way to block the UI in WebPOS is using Process Controller's scrims.

A process controller's scrim is defined within the Process Controller definition itself. The available scrims are:

At the start of a process, the logic will check if it is necessary to show the scrim (i.e. it is the first process with that scrim type defined) or not.

At the end of a process, the logic will check if the scrim should be hidden (i.e. there is no other processes with the same scrim) or not.

Subscribe a component to the Process

To know when a process starts/finishes we need to subscribe the component to it in order to get that information from Process Controller API.

It is simple, we just need to to subscribe the component inside initComoponents of our button and unsubscribe it in destroyComponents (we need to unsubscribe also because we do not want destroyed components registered). As parameter we will pass an array of the searchKeys of the processes to listen to.

See an example:

  processesToListen: ['searchKey1', 'searchKey2']
  initComponents: function () {
    OB.UTIL.ProcessController.subscribe(this.processesToListen, this);
  destroyComponents: function () {
    OB.UTIL.ProcessController.unSubscribe(this.processesToListen, this);

Bulbgraph.png   If your component extends from OB.UI.Button or OB.UI.Modal you only need to define processesToListen array

Implement functions of process start/finish for the component

Finally, we need to implement what we want to do before and after the process. We can disable a button while the process is executing or show 'Loading...' screen or hide a component...

Defined these two functions:

* processStarted: function (process, execution, processesInExec) * processFinished: function (process, execution, processesInExec)

We will receive some information that would help us in our implementation. process is the event that starts/finishes and inside it has lists of components subscribed to it and executions in progress. execution will give us the id of the current execution and finally processesInExec will be a list of processes in execution for this component.

See an example:

  processStarted: function (process, execution, processesInExec) {
    if (processesInExec.models.length === 1 && process.get('executions').models.length === 1) {
      if (this.disableButton) {
  processFinished: function (process, execution, processesInExec) {
    if (processesInExec.models.length === 0) {
      if (this.enableButton) {

Bulbgraph.png   If your component extends from OB.UI.Button or OB.UI.Modal by default the component will be disabled while the execution is in progress. You don't need to implement those functions but you can extend them or override them
Bulbgraph.png   A process can have more than one execution at the same time. If you want to execute these functions just with the first start and with the last finish, you can use the if implementation of the example

Retrieved from ""

This page has been accessed 1,943 times. This page was last modified on 27 February 2019, at 14:52. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.