Scripting on Business Process Flow in CRM 2015

With the introduction of MS CRM 2015, came many new features. The one we are going to discuss here is advancement of Business Process Flow and especially the Scripting part, which came as boon.

Before CRM 2015, the Business Process Flow exist, but no API availability made it impossible for the developers to interact with the BPF via programming.

CRM 2015 gave it a new look, while creating a Business Process Flow, we have the option of creating Branched stages, which in simple terms is we can conditionally decide which stage to be shown after the current stage. The branching decisions can be made on the basis of the value of any step used for the current stage.

Previously we were not allowed to visit an entity more than once before, now we can visit an entity more than once.

Above are the few highlights of features added for BPF, let`s delve into the Programmability enhancement.

The most important part is, How to hook to the Stage change or Stage Select events of BPF? This is indeed the simplest part.

Example:

If you want to hook to the Stage change event, you can do this by writing the below code. And, you have the freedom to place this code either onLoad or onSave of the form or else on change of any field.

//Register a function on change of the stage

Xrm.Page.data.process.addOnStageChange(stageChange);

stageChange – It is the function to be called when the stage is changed.

Similarly, you can hook onto the Stage select event.

//Register a function on select of a stage

Xrm.Page.data.process.addOnStageSelected(stageSelected);

stageSelected – It is the function to be called when the stage is selected.

We have the options to unhook the events as well.

//Unbind a function on change of the stage

Xrm.Page.data.process.removeOnStageChange(stageChange);

//Unbind a function on select of a stage

Xrm.Page.data.process.removeOnStageSelected(stageSelected);

By hooking onto either stage change or stage select events, we have plethora of options to use.

Like we mentioned above, that we can Branch the entities conditionally. We can leverage this functionality by showing different fields for an entity depending on the value selected for the step on the previous stage.

Let us explain you few of the available methods in this part of the Blog, and the rest in this.

• Collapse or Expand the Business Process Flow:

We have the option to collapse the Business Process Flow by default, on load of the form.

Snippet:

Xrm.Page.ui.process.setDisplayState(string)

string: “expanded”  or “collapsed” are the two variables that can be passed.

• Show/Hide the Business Process Flow:

We can show or hide the business flow. It can be useful when we don`t need few of the Security Roles to see the BPF.

Snippet:

Xrm.Page.ui.process.setVisible(bool)

bool: “true” to show and “false” to hide.

• Active Process:

We can get the Current Active Process and we can set the Current Active Process. This is useful if you want different security profiles to see different processes.

• getActiveProcess

This will give you the object of the current Active Process. Object will have,

Process Name, Process Id(GUID), Render State(Visible/Hidden) & Collection of Stage Objects.

Snippet:

var procObj = Xrm.Page.data.process.getActiveProcess();

• setActiveProcess

This will allow you to set the Active Process.

Snippet:

Xrm.Page.data.process.setActiveProcess(procGUID, callbackFunction);

procGUID: Id of the process to be set.

callbackFunction: Function that will be called in order we have any necessary actions to be performed on setting the process.

• Active Stage:

We can get the Current Active Stage and we can also set the Current Active Stage. This is useful if you want a user to move back to previous stage, when he selects “x” value for a step on current Active stage.

• getActiveStage

This  will give you the object of current Active Stage. Object will have, Stage Name, Stage ID(GUID), Base Entity, Stage Status(active/inactive) & Collection of Step objects.

            Snippet:

var actStg = Xrm.Page.data.process.getActiveStage();

• setActiveStage

This will allow you to set an Active Stage.

Note: Only completed stage for the current entity can be set using this method.

            Snippet:

Xrm.Page.data.process.setActiveStage(stgGUID, callbackFunction);

stgGUID: ID of the stage to be set.

callbackFunction: If in case any actions are to be performed after setting the Active Stage.

• Get the Active Path

We can get the Active Path i.e., serves the exact seq. of stages that got the user to where he is now, the stage he is on and the predicted set of future stages on the basis of Branching rules.

Snippet:

var stgColl = Xrm.Page.data.process.getActivePath()

• Get the Enabled Processes

We can get the list of enabled processes for a particular entity which user can use to switch.

Snippet:

Xrm.Page.data.process.getEnabledProcess(callbackFunction(enabledProcesses))

callbackFunction(enabledProcesses) :  This callback function will accept a parameter. The parameter will be an object having the list of enabled processes.

• Navigate Previous or Next

What if you want to move the user next or prev depending on the value of a step on the current stage, to make that happen, we have 2 functions:

• moveNext:

This will move the user to the next stage.

Snippet:

Xrm.Page.data.process.moveNext(callbackFunction)

callbackFunction: The callback function can be used to perform any actions that needs to be done after moving the user to the next stage.

• movePrevious:

This will move the user to the previous stage.

Snippet:

Xrm.Page.data.process.movePrevious(callbackFunction)

callbackFunction: The callback function can be used to perform any actions that needs to be done after moving the user to the previous stage.

• Process Methods

In the first part of the blog, we discussed how to retrieve Active Process. Now, let`s see how to retrieve the properties from the returned object.

var procObj = Xrm.Page.data.process.getActiveProcess();

• Get the Id:

procObj.getId();

Returns a string.

• Get the Name:

procObj.getName();

Returns a string.

• Get the Stage Collection:

procObj.getStages();

Returns the collection of stages

• Check whether the process is rendered or not:

procObj.isRendered();

Returns a bool.

• Stage Methods

In the first part of the blog, we discussed how to retrieve Active Stage. Now, let`s see how to retrieve the properties from the returned object.

var actStg = Xrm.Page.data.process.getActiveStage();

• Get the Category:

actStg. getCategory().getValue();

Returns an integer value of the Business Process Flow category.

• Get the Entity Name:

actStg.getEntityName();

Returns the logical name of the entity.

• Get the Id:

actStg.getId();

Returns a string.

• Get the Stage Name:

actStg.getName();

Returns a string.

• Get the Status:

actStg.getStatus();

Returns “active” or  “inactive”.

• Get the Steps:

var stpColl = actStg.getSteps();

Returns collection of steps.

• Step Methods:

In the previous point, we got the step collection. Now, let`s see how to retrieve the properties from the returned object.

• Get the Logical Name:

stpColl.getAttribute();

Returns the logical name of the step.

• Get the Name of the step:

stpColl.getName();

Returns the step name.

• Get the Required Level:

stpColl.isRequired();

Returns a bool.

All these are new addition in the CRM 2015 box and those are the most asked and helpful additions. We can achieve many things by hooking onto stage change and stage select events.