While most of the JavaScript model has remained the same from Microsoft Dynamics CRM 2011, CRM 2015 features some handy new JavaScript for manipulating Business Process Flows. In today’s blog, we will delve into some helpful hints that will come in handy when utilizing this functionality. Let’s begin!
Business Process Flows are now accessible via Xrm.Page.data.process. The new methods are as follows:
getActiveProcess()
This will return the currently active process object. Further methods are available for the process which can be viewed here.
setActiveProcess(processId, callbackFunction)
This will change the active process to the one referenced by the ID. The callback function will be passed by either a “success” or “invalid” string.
getActiveStage()
This will return the active stage object. Further methods are available for the stage which can be viewed here.
setActiveStage(stageId, callbackFunction)
This method can set a completed stage as the active stage. It will not work for setting a stage that has not been completed, and the selected stage must be the active stage. After 2015 Update 1, you can go across entities with this method.
The callback function will pass a string value from the following list:
- Cross Entity – should only occur prior to Update 1 when trying to cross entities
- Invalid – error due to either a stageid that doesn’t exist, an active stage that isn’t selected, or the record is not yet saved
- Unreachable – The stage exists on a different path
- dirtyForm – the form has data that has not been saved (more on this below)
getActivePath()
This will return an object with stages that are in the current path and methods to interact with those stages that are part of the Business Process Flow.
getEnabledProcess(callbackFunction(enabledProcesses))
This will return an object with an array including the enabled process ID as well as its name. In order to gather this information, you have to build a local function. In the example below, we load an array with the available processes and then report the results to the console.log.
function getAvailableProcesses() {
availableProcess = [];
Xrm.Page.data.process.getEnabledProcesses(
function (processList) {
for (i in processList){
availableProcess.push({id: i, name: processes[i]})
}
console.log(“Successfully gathered processes into array”);
if (availableProcess.length<0) console.log(“No available processes for this entity”);
else{
for(i in availableProcess){
console.log(“id: “+ availableProcess[i].id +” name: “+availableProcess[i].name);
}
}
});
}
getSelectedStage()
Use this method after 2015 Update 1 tol return an id for the currently selected stage.
moveNext(callbackFunction)
This will cause the Business Process Flow to move to the next stage. Note that this cannot be used to move to the next stage if it is on another entity (1:N relationship). The callback function will be passed on one of the following strings:
- Success – operation succeeded
- crossEntity – the next stage is on a different entity
- End – the active stage is the last of the active path
- Invalid – the operation failed because the selected stage is not the active stage
- dirtyForm – the page has not been saved (see notes below)
movePrevious(callbackFunction)
This will move to the previous stage. If you have Update 1 for CRM 2015 you will be able to navigate to a previous stage, even if it is on a different entity. The callback function will be passed on one of the following strings:
- Success – operation succeeded
- crossEntity – the next stage is on a different entity
- Beginning – the active stage is the first of the active path
- Invalid – the operation failed because the selected stage is not the active stage
- dirtyForm – the page has not been saved (see notes below)
BPF moveNext and dirtyForms
With CRM 2015, the moveNext() function was updated to prevent moving to the next stage if the form was dirty, despite the fact that moving the Business Process Flow calls for saving the form. If you’re attempting to moveNext() onSave a form, you will now get a dirtyForm returned in your callback function and the flow will not move. To work around this, you can use the following code:
function moveNext(currentStage) {
//Method is used to attempt to move to the next stage in the Business Process Flow
//currentStage is expected to be the current stage name of the record when this method is to be invoked
//console.log(“moveNext requested for stage: ” + Xrm.Page.data.process.getActiveStage().getName());
var pollingAttemptsRemaining = 10;
var intervalId;
//Cycle through code every 2 seconds for dirty check
intervalId = setInterval(function () {
pollingAttemptsRemaining -= 1;
//console.log(“Attempts Remaining: ” + pollingAttemptsRemaining);
//Check if the current stage is the same stage that record was in when calling moveNext
//This check is in place after 2015 SP1 due to changes in CRM code handling of moveNext with being called onSave with a dirty form
//Out Of Box moveNext calls an additional save which causes code to be executed twice, this prevents further execution
if (Xrm.Page.data.process.getActiveStage().getName() != currentStage) {
clearInterval(intervalId);
}
//Check if form is dirty, if it is not and the stage has not changed then attempt to moveNext
if (!Xrm.Page.data.entity.getIsDirty() && Xrm.Page.data.process.getActiveStage().getName() == currentStage) {
console.log(“attempting move”);
Xrm.Page.data.process.moveNext(moveResult);
pollingAttemptsRemaining = 0;
clearInterval(intervalId);
}
//If number of attempts remaining has passed exit code
if (pollingAttemptsRemaining <= 0) {
clearInterval(intervalId);
}
}, 200);
Using this method will allow you to moveNext() on Save even if the form is dirty on save, as it will continue to cycle while waiting for the save to complete and then will try triggering the move again. This can be used as a work around.
That’s all for the blog today, folks! If you would like to learn more about CRM 2011 or CRM 2015, check out our website! Until next time, happy CRM’ing!