Dynamics BPF Javascript: NEW onPreStageChange Handler!

If you are utilizing the UCI interface there is a new JavaScript handler available for the Business Process Flows (BPF), onPreStageChange.  Unlike the onStageChange handler onPreStageChange fires before the actual business process has been changed so that you can evaluate if you want the change to occur and prevent it if needed.

With this new handler we can now get rid of many of the Synchronous workflows used previously to evaluate the changes made to a BPF.  By removing these workflows the overall performance of your BPF changes should be increased.  Additionally calling JavaScript code being before the change also eliminates additional problems such as the users clicking the Next/Previous multiple times before the workflows have been fired (Tip #360

To utilize the new handler you will needed to create a function and then pass that function into the addOnPreStageChange function provided under executionContext.getFormContext().data.process.  It is best practice to pass a function rather than using an anonymous function because it will allow you to remove the handler later if needed.  Additional documentation for these function can be found here

 function onLoad(executionContext) {
        var formContext = executionContext.getFormContext();
        var process = formContext.data.process;        

        //handles changes to the BPF before they actually occur
        process.addOnPreStageChange(myProcessStateOnPreChange);
    }

function myProcessStateOnPreChange() {

        var formContext: Xrm.FormContext = executionContext.getFormContext();
        var process = formContext.data.process;
        var eventArgs = executionContext.getEventArgs();

        var currentStageId = process.getActiveStage().getId();
        var nextStageId = process.getSelectedStage().getId();

        //dont allow to go back using the set active button
        if (currentStageId != nextStageId) {
            eventArgs.preventDefault();
            Xrm.Utility.alertDialog("You cannot use the Set Active button.")
            return;
        }        
              
        if (eventArgs._direction === 1) //backwards
        {            
            //here you can add logic based upon the BPF going to the previous Stage.
            return;
        }

        //otherwise forward
        // here you can add logic based upon the BPF going to the next Stage.   
    }

Comments

  1. Hi Rick,
    Thanks a lot for your code. It seems to do exactly what I want. In my case: trigger a popup alert each time before passing to the next stage. However, I have a problem: this line seem to not go through:

    var formContext: Xrm.FormContext = executionContext.getFormContext();

    with this I always get an error

    and if I try var formContext = executionContext.getFormContext();

    it won't work because executionContext is does not exist.
    In fact my issue is : we can pass execution context in the function called onLoad:

    onLoad(executionContext) but how can we pass the same to myProcessStateOnPreChange() ?
    Thanks a lot for your help

    Best Regards
    Pietro Maffei

    ReplyDelete
    Replies
    1. Hi Pietro,

      the construct used works only when using pure TypeScript. This can be changed:

      To the function mentioned in addOnPreStageChange() the execution context is automatically passed as the first parameter to the function. Thus working code would be:

      function myProcessStateOnPreChange(executionContext) {

      var formContext = executionContext.getFormContext();
      ...

      hope that helps

      Jeroen

      Delete
  2. Hi Jeroen,

    Do you know if this new handler Is available on On-Premise Environments?

    ReplyDelete

Post a Comment

Popular posts from this blog

Add User As Local Administrator On Domain Controller

Calling Dataverse Web API in PowerShell using Client Credentials

Windows Server 2008R2 VMs Shut Down After 1 to 2 Hours