Control Next and Previous stage movement in Dynamics 365/ CDS Business Process flows using Client API / PowerApps

 

Honestly I was not aware of this function sometime back and this was purely an accidental discovery. And guess what when I queried around, I found that it actually missed the cognizance of so many consultants out there. And while this function have been introduced, we still keep telling the customer that it is kind of not possible to show something like a user confirmation before stage movement.

You may argue that “OnStageChange” event has been there from the beginning. However the issue with it is, it fires when the stage have already changed. Hence does not make any sense.

In the below example I am going to show you couple of scenarios. And trust me if you are not aware of this and seeing for the first time, it will be a huge sense of relief for you since this is a kind of requirement which pops up every now and then.

• Getting user confirmation before the stage movement happens
• Stop back stage movement.

Below is the sample code that I have set up for account entity form

var Acc = {};
Acc.formEvents = {
    stageMovementConfirmed: false,




   form_load: function (e) {
       var fc = e.getFormContext();                     
       fc.data.process.removeOnPreStageChange(Acc.formEvents.handlePreStage);
       fc.data.process.addOnPreStageChange(Acc.formEvents.handlePreStage);
    },




   handlePreStage: function (e) {
       debugger;




      // get the event arguments
       var bpfArgs = e.getEventArgs();




      if (bpfArgs.getDirection() === "Previous") // back stage movement is not allowed;
       {
          bpfArgs.preventDefault();
          var alertStrings = { confirmButtonLabel: "OK", text: "Back stage movement is not allowed", title: "Sample title" };
          var alertOptions = { height: 120,  260 };
          Xrm.Navigation.openAlertDialog(alertStrings, alertOptions);
          return;
       }




      // this will fire again when move next is called.
       // so if stage movement has been allowed earlier, please proceed. else ask for user confirmation.
       if (Acc.formEvents.stageMovementConfirmed === true) {
          Acc.formEvents.stageMovementConfirmed = false;
          return;
       }




      if (bpfArgs.getDirection() === "Next") { // only next stage movement is allowed.




         // stop the stage movement
          bpfArgs.preventDefault();




         var confirmStrings = { text: "Are you sure you want to move to the next stage?", title: "Stage movement Confirmation!" };
          var confirmOptions = { height: 150,  300 };
          Xrm.Navigation.openConfirmDialog(confirmStrings, confirmOptions).then(
             function (success) {
                if (success.confirmed) {
                   Acc.formEvents.stageMovementConfirmed = true;
                   e.getFormContext().data.process.moveNext();
                }
             });
       }




      // you can also play with the other properties of eventargs
       // get the stage - bpfArgs.getStage();
       // get the steps - bpfArgs.getStage().getSteps();




   }
};

Well, it’s a very simple code. The form_load event is fired on account form load and registers the function handlePreStage on Business process “onPreStageChange” event.

The remaining part is self explanatory and I have basically put all the code with appropriate comments to highlight what all you can do with this function.

All set and done, below is the experience I get when I try this out.