Dynamics CRM Scripting for Business Process Flows

Dynamics CRM 365/ Dynamics CRM 2015/ CRM 2016 lets the developers interact with the business process flows by writing client-side scripts. Business Process flow actions can be performed programmatically by making use of the methods under Xrm.Page.data.process and Xrm.Page.ui.process namespaces.

To interact with the business process flow, in addition to the entity form events, two new events onStageChange() and onStageSelected() event are provided by the client API.

Below is the list of methods for tapping into the  Business Process Flow capability.

Method Description Implementation
Process Methods
getEnabledProcesses –  Executes asynchronously

–  Retrieves the information about all the business process flows enabled for the entity

–  Returns a dictionary object where Id is the key and Name is the value

//GetEnabledProcesses

Xrm.Page.data.process.getEnabledProcesses(function (processes) {

for (var processId in processes) {

alert(“Id:” + processId + “, Name:” + process[processId]);

}

});

setActiveProcess –  Executes asynchronously

–  Sets the business process flow for the entity passed as a parameter

–  Returns the status of the operation (success or invalid)

// Set Active Process

Xrm.Page.data.process.setActiveProcess(processId, function (status) {

alert(status);

});

getActiveProcess –  Retrieves the information about the active business process flow for the entity

–   Returns an object containing the data for the active process

var id, processName, stageCount;

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

if (activeProcess != null) {

// Get Process Id

id = activeProcess.getId();

// Get Process Name

processName = activeProcess.getName();

// Get Process stage count

stageCount = activeProcess.getStages().getLength();

}

setDisplayState –  Displays the business process flow as expanded or collapsed

–  Display state is passed as a string parameter to the function

if (Xrm.Page.ui.process.getDisplayState() == “collapsed”) {

// Set the display as expanded

Xrm.Page.ui.process.setDisplayState(“expanded”);

}

else {

// Set the display as collapsed

Xrm.Page.ui.process.setDisplayState(“collapsed”);

}

setVisible –  Shows or hides the business process flow

–  Boolean parameter to show (true) or hide (false) the process

if (!Xrm.Page.ui.process.getVisible()) {

// Show the business process flow

Xrm.Page.ui.process.setVisible(true);

}

else {

// Hide the business process flow

Xrm.Page.ui.process.setVisible(false);

}

Stage Methods
getStages –  Retrieves the information about a specific stage in the process identified by the index value

–  Returns an object containing the data related to a particular stage in a process

var stageObj,stageId, stageName, stageEntityName, stageCategory, stageStatus;

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

if (activeProcess != null) {

// Get the First stage object of the process

stageObj = activeProcess.getStages().get(0);

// Get Stage Id

stageId = stageObj.getId();

// Get Stage Name

stageName = stageObj.getName();

// Get Stage Entity name

stageEntityName = stageObj.getEntityName();

// Get Stage Category

stageCategory = stageObj.getCategory().getValue(); // – integer value of the stage

// Get Stage Status

stageStatus = stageObj.getStatus(); // – active/inactive

}

getActiveStage –  Returns an object representing the current active stage of the process var activeStage;

// Get Active Stage object

activeStage = Xrm.Page.data.process.getActiveStage();

setActiveStage –  Executes asynchronously

–  Sets a completed stage for the current entity as the active stage

// Sets the Stage identified by the id as the active stage

Xrm.Page.data.process.setActiveStage(stageId, function (data) {

alert(data);

});

getActivePath –  Retrieves a collection of stages currently in the active path.

–  Contains information for completed stages, current active stage as well as predicted future stages based on the data on the current record and branching rules for the process

 

// Get Active Path

var activePath = Xrm.Page.data.process.getActivePath();

if (activePath != null) {

activePath.forEach(function (stage, n) {

alert(” Stage Index: ” + n + “\n Entity: ” + stage.getEntityName() + “\n StageId: ” + stage.getId() + “\n Status: ” + stage.getStages());

 

})

 

}

Step Methods
getSteps –  Retrieves the information of all the steps in a particular stage of the process var stepCollection, stepCount, stepObj,stepName,stepAttributeName,isStepReq,stepType;

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

if (activeStage) {

 

// Get Step count

stepCount = activeStage.getSteps().getLength();

// Get the Steps of a stage

stepCollection = activeStage.getSteps();

// Get the First Step object of the stage

stepObj = activeStage.getSteps().get(0);

// Get the Step Name

stepName = stepObj.getName();

// Get the Step Attribute name

stepAttributeName = stepObj.getAttribute();

// Check whether the Step is required

isStepReq = stepObj.isRequired();

// Get the Step type

stepType = stepObj.getStepType();

}

Navigation Methods
moveNext –  Progresses the process to the next stage

–  Works only when the selected stage and the active stage are the same

–  Triggers the onStageChange event

–  Returns the status in a callback function indicating the operation status (success, crossEntity, end, invalid)

// Move Next

Xrm.Page.data.process.moveNext(function (status) {

if(status == “success”)

alert(“Moved to next stage”);

});

movePrevious –  Moves the process to the previous stage

–  Works only when the selected stage and the active stage are the same

–  Triggers the onStageChange event

–  Returns the status of the operation

// Move Previous

Xrm.Page.data.process.movePrevious(function (status) {

if(status == “success”)

alert(“Moved to previous stage”);

});

 

Event Handler Methods
addOnStageChange –  Adds a function as an event handler for the onStageChange event

–  Event handler function executes when Next or Previous button is clicked on the process UI

// Add onStageChange event handler

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

 

function stageChanged(execContext)

{

// Get direction

var direction = execContext.getEventArgs().getDirection();

// Get the current stage object

var currentStage = execContext.getEventArgs().getStage();

}

removeOnStageChange –  Removes a function as an event handler for the onStageChange event // Remove onStageChange event handler

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

addOnStageSelected –  Adds a function as an event handler for the onStageSelected event

–  Event handler function executes whenever a stage of an business process flow is selected

// Add onStageSelected event handler

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

 

function stageSelected(execContext)

{

// Gets the current stage

var currentStage = execContext.getEventArgs().getStage();

}

removeOnStageSelected –  Removes a function as an event handler for the onStageSelected event // Remove onStageSelected event handler

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

Hope you will find it useful!

Cheers
Swaroop
Adisys Engineering Team

Advertisements

Dynamics CRM 2015 – Turn off the Navigation Tour permanently

The Navigation tour was introduced in CRM 2013. It shows up to users each time they access the system and user can select the “Don’t show me this again” check box to turn it off. However this configuration is temporarily stored in user’s local browser cache hence it will re-appear after cleaning up the cache or access the CRM from different device.

crm navigation & settings

crm navigation & settings

 

Now with the latest CRM 2015, system administrator has a way to enable/disable the Navigation Tour page permanently for the whole organization. Following is the definition of this new flag on MSDN:

Set whether users see navigation tour
Display navigation tour to users when they sign in When users start CRM, they’re presented with a welcome screen (navigation tour) that provides a quick overview of CRM. Choose No to disable this tour for all users in your organization.NoteThis feature is available if you’re using CRM Online and you have installed the 2015 Update, or if you’re using CRM 2015.

 

To do that, go to Microsoft Dynamics CRM > Settings > Administration > System settings > General tab. In Set whether users see navigation tour, set the Display navigation tour to users when they sign in to No, as shown below:

The details can be found on https://technet.microsoft.com/en-us/library/dn832123.aspx

crm navigation2

I hope you find it useful!

Author: Zhe Chen
Title: Lead Dynamics CRM Consultant @ Adisys
Email: zhechen@adisys.co

Dynamics CRM 2015 – Interact with the Business Process Flow controls in the form

With Microsoft Dynamics CRM 2015, the Xrm.Page.data.process namespace provides events, methods, and objects to interact with the business process flow data in a form.

This sample demonstrates how to switch to different stage using the new Xrm.Page.data.process methods.

Followings are the API used in the sample code:

getActiveProcess() – retrieve information about the active process

setActiveProcess()- Set different process as the active process.

getActiveStage()- retrieve information about the active stage

setActiveStage() – set a different stage as the active stage.

getActivePath() – get a collection of stages currently in the active path with methods to interact with the stages displayed in the business process flow control.

addOnStageChange(),removeOnStageChange() – add or remove event handlers for the business process flow control.

addOnStageSelected() – add a function as an event handler for the OnStageSelected event so that it will be called when a business process flow stage is selected.

removeOnStageSelected() – remove a function as an event handler for the OnStageSelected event.

moveNext()- move to the next stage

movePrevious()- Moves to the previous stage.

stageObj.getId() – Returns the unique identifier of the stage

stageObj.getName() – Returns the name of the stage

getEnabledProcesses() – retrieve the enabled business process flows that the user can switch to for an entity

 

Followings are the Javascript to demonstrate how to switch the process stage:

//move to new stage by stage name

function moveToStage(newStageName){

 

//get active stage

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

var activeStageName = activeStage.getName();

//get a collection of stages currently in the active path

var activePathCollection = Xrm.Page.data.process.getActivePath();

//Enumerate the stages

activePathCollection.forEach(function (stage, n) {

var name = stage.getName();

//search for specific stage by name

if( (newStageName == name) && (newStageName != activeStageName) ) {

//move to the new stage

Xrm.Page.data.process.setActiveStage(stage.getId() , onSetActiveStage);

}

})

}

 

//This callback function is passed the result to indicate whether the setActiveStage operation succeeded.

function onSetActiveStage(returnStatus){

switch (returnStatus) {

case “success”:

break;

case “crossEntity”:

alert(“crossEntity!”);

break;

case “unreachable”:

alert(“unreachable stage”);

break;

case “invalid”:

alert(“invalid stage”);

break;

}

}

 

//Progresses to the next stage

function moveNext(){

Xrm.Page.data.process.moveNext(onMoveNext);

}

 

//This callback function is passed the result to indicate whether the moveNext operation succeeded.

function onMoveNext(returnStatus){

switch (returnStatus) {

case “success”:

break;

case “crossEntity”:

alert(“crossEntity!”);

break;

case “end”:

alert(“Last stage”);

break;

case “invalid”:

alert(“invalid stage”);

break;

}

}

//Progresses to the next stage

function movePrevious(){

Xrm.Page.data.process.movePrevious(onMovePrevious);

}

 

//This callback function is passed the result to indicate whether the movePrevious operation succeeded.

function onMovePrevious(returnStatus){

switch (returnStatus) {

case “success”:

break;

case “crossEntity”:

alert(“crossEntity!”);

break;

case “beginning”:

alert(“Stage beginning”);

break;

case “invalid”:

alert(“invalid stage”);

break;

}

}

 

// Methods to manage event handlers

// on form load

function registerProcessEvent(){

//add OnStageChange event handlers for the business process flow control.

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

//add OnStageSelected event handlers for the business process flow control.

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

 

//show current process

retrieveActiveProcess();

 

//show current stage

retrieveActiveStage()

 

}

 

//Retrieve active process

function retrieveActiveProcess(){

//Get active process

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

var processName = activeProcess.getName();

var processID = activeProcess.getId();

alert(“Acitve process is ” + processName + ” ID = ” + processID);

}

//Retrieve active stage

function retrieveActiveStage(){

//Get active stage

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

var stageName = activeStage.getName();

var stageID = activeStage.getId();

alert(“Acitve stage is ” + stageName + ” ID = ” + stageID);

}

 

//event handler for Stage Change

function onStageChange(){

alert(“On stage change event”);

}

 

//event handler for Stage Selected

function onStageSelected(){

alert(“On stage Selected event”);

}

 

I hope you find it useful!

 

 

Author: Zhe Chen
Title: Lead Dynamics CRM Consultant @ Adisys
Email: zhechen@adisys.co