Xrm.Page.data.process (client-side reference)

 

Updated: November 29, 2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

The Xrm.Page.data.process namespace provides events, methods, and objects to interact with the business process flow data in a form.

See Xrm.Page.ui.process (client-side reference) for methods to interact with the business process flow control in the form.

ActiveProcess methods

Use getActiveProcess to retrieve information about the active process and setActiveProcess to set a different process as the active process.

ProcessInstance methods

Use getProcessInstances to retrieve information about all the process instances for an entity record and setActiveProcessInstance to set a process instance as the active instance.

ActiveStage methods

Use getActiveStage to retrieve information about the active stage and setActiveStage to set a completed stage as the active stage.

You can use setActiveStage to a stage in a different entity.

getActivePath

Use this method to get a collection of stages currently in the active path with methods to interact with the stages displayed in the business process flow control.

The active path represents stages currently rendered in the process control based on the branching rules and current data in the record.

getEnabledProcesses

Use this method to asynchronously retrieve the enabled business process flows that the user can switch to for an entity.

getSelectedStage

Use this method to access the currently selected stage.

Methods to manage event handlers

Use the addOnStageChange, removeOnStageChange, addOnStageSelected,  removeOnStageSelected, addOnProcessStatusChange, and removeOnProcessStatusChange methods to add or remove event handlers for the business process flow control.

Navigation methods

Use moveNext to move to the next stage and movePrevious to move to the previous stage.

You can use movePrevious to a previous stage in a different entity.

Process methods

Use process methods to access properties of the process.

Instance methods

Use process instance methods to access properties of the current process instance.

Stage methods

Use stage methods to access properties of the stage in a business process flow.

Step methods

Use step methods to access properties of the step in a in a stage in a business process flow.

Use getActiveProcess to retrieve information about the active process and setActiveProcess to set a different process as the active process.

Returns a Process object representing the active process.

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

Type: Process

Remarks: See Process methods for the methods to access the properties of the process returned.

Set a Process as the active process.

If there is an active instance of the process, the entity record is loaded with the instance ID. If there is no active instance of the current process, a new process instance is created and the entity record is loaded with the instance ID. If there are multiple instances of the current process, the record is loaded with first instance of the active process as per the defaulting logic, that is the most recently used process instance per user.

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

Parameters:

processId

Type:String

Remarks: The Id of the process to make the active process.

callbackFunction

Type:Function

Remarks: A function to call when the operation is complete. This callback function is passed one of the following string values to indicate whether the operation succeeded.

Value

Description

success

The operation succeeded.

invalid

The processId isn’t valid or the process isn’t enabled.

Use getProcessInstances to retrieve information about all the process instances for an entity record and setActiveProcessInstance to set a process instance as the active instance.

System_CAPS_noteNote

These methods were introduced in December 2016 update for Dynamics 365 (online and on-premises).

Returns all the process instances for the entity record that the calling user has access to.

Xrm.Page.data.process.getProcessInstances(callbackFunction(object));
Parameter

Type:Function

Remarks: The callback function is passed an object with the following attributes and their corresponding values as the key: value pair.

  • CreatedOn

  • ProcessDefinitionID

  • ProcessDefinitionName

  • ProcessInstanceID

  • ProcessInstanceName

  • StatusCodeName

The process instances are filtered according to the user’s privileges.

Sets a process instance as the active instance.

Xrm.Page.data.process.setActiveProcessInstance(processInstanceId, callbackFunction);

Parameters:

processInstanceId

Type:String

Remarks: The Id of the process instance to set as the active instance.

callbackFunction

Type:Function

Remarks: A function to call when the operation is complete. This callback function is passed one of the following string values to indicate whether the operation succeeded.

Value

Description

success

The operation succeeded.

invalid

The processInstanceId isn’t valid or the process isn’t enabled.

Use getActiveStage to retrieve information about the active stage and setActiveStage to set a different stage as the active stage.

Returns a Stage object representing the active stage

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

Type: Stage

Remarks: See Stage methods for the methods to access the properties of the stage returned.

Set a completed stage as the active stage.

System_CAPS_noteNote

After Microsoft Dynamics CRM Online 2015 Update 1, you can use this method to set a stage in a different entity.

Only a completed stage for the entity can be set using this method.

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

Parameters:

stageId

Type:String

Remarks: The ID of the completed stage for the entity to make the active stage.

callbackFunction

Type:Function

Remarks: An optional function to call when the operation is complete.

The callback function will be passed a string value of “success” if the operation completes successfully.

If the stageId represents a stage that isn,t valid, the stage won’t be made active and the callback function will be passed a string value indicating the reason. The values listed in the following table may be returned.

Value

Reason

invalid

There are three reasons why this value may be returned:

  • The stageId parameter is a non-existent stage ID value.

  • The active stage isn’t the selected stage

  • The record hasn’t been saved yet.

unreachable

The stage exists on a different path.

dirtyForm

This value will be returned if the data in the page is not saved.

System_CAPS_importantImportant

This method can only be used when the selected stage and the active stage are the same. When your code is initiated from the OnStageChange event, the current stage will be selected. When your code is initiated from the OnStageSelected event, you should use Xrm.Page.data.process.getActiveStage to verify that the selected stage is also the active stage. For any other form event, it isn’t possible to determine which stage is currently selected. For best results, this method should only be used in code that is called in functions initiated by the OnStageChange and OnStageSelected events.

Use this method to get a collection of stages currently in the active path with methods to interact with the stages displayed in the business process flow control.

The active path represents stages currently rendered in the process control based on the branching rules and current data in the record.

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

Example:

See Sample: Xrm.Page.data.process.getActivePath for sample using this method.

Return Value

Type: Collection

Remarks: A collection of all completed stages, the currently active stage, and the predicted set of future stages based on satisfied conditions in the branching rule. This may be a subset of the stages returned with Xrm.Page.data.process.getActiveProcess because it will only include those stages which represent a valid transition from the current stage based on branching that has occurred in the process.

Use this method to asynchronously retrieve the enabled business process flows that the user can switch to for an entity.

Xrm.Page.data.process.getEnabledProcesses(callbackFunction(enabledProcesses));
Parameter

Type:Function

Remarks: The callback function must accept a parameter that contains an object with dictionary properties where the name of the property is the Id of the business process flow and the value of the property is the name of the business process flow.

The enabled processes are filtered according to the user’s privileges. The list of enabled processes is the same ones a user can see in the UI if they want to change the process manually.

Example:

See Sample: Xrm.Page.data.process.getEnabledProcesses for a sample using this method.

Use this method to get the currently selected stage.

Xrm.Page.data.process.getSelectedStage()
Return Value

Type: Stage

The currently selected stage.

Remarks

See Stage methods for the methods to access the properties of the stage returned.

Use these methods to add or remove event handlers for the business process flow control.

Use this to add a function as an event handler for the OnStageChange event so that it will be called when the business process flow stage changes.

Xrm.Page.data.process.addOnStageChange(handler);
Parameter

Type: function reference

Remarks: The function will be added to the bottom of the event handler pipeline. The execution context is automatically set to be the first parameter passed to the event handler. See Execution context (client-side reference) for more information.

You should use a reference to a named function rather than an anonymous function if you may later want to remove the event handler.

Use this to remove a function as an event handler for the OnStageChange event.

Xrm.Page.data.process.removeOnStageChange(handler);
Parameter

Type: function reference

Remarks: If an anonymous function is set using the addOnStageChange method it cannot be removed using this method.

Use this to 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.

Xrm.Page.data.process.addOnStageSelected(handler);
Parameter

Type: function reference

Remarks: The function will be added to the bottom of the event handler pipeline. The execution context is automatically set to be the first parameter passed to the event handler. See Execution context (client-side reference) for more information.

You should use a reference to a named function rather than an anonymous function if you may later want to remove the event handler.

Use this to remove a function as an event handler for the OnStageSelected event.

Xrm.Page.data.process.removeOnStageSelected(function reference);
Parameter

Type: function reference

Remarks: If an anonymous function is set using the addOnStageSelected method it cannot be removed using this method.

Use this to add a function as an event handler for the OnProcessStatusChange event event so that it will be called when the business process flow status changes.

Xrm.Page.data.process.addOnProcessStatusChange(handler);
Parameter

Type: function reference

Remarks: The function will be added to the bottom of the event handler pipeline. The execution context is automatically set to be the first parameter passed to the event handler. See Execution context (client-side reference) for more information.

You should use a reference to a named function rather than an anonymous function if you may later want to remove the event handler.

This method was introduced in December 2016 update for Dynamics 365 (online and on-premises).

Use this to remove a function as an event handler for the OnProcessStatusChange event event.

Xrm.Page.data.process.removeOnProcessStatusChange(handler);
Parameter

Type: function reference

Remarks: If an anonymous function is set using the addOnProcessStatusChange method it cannot be removed using this method.

This method was introduced in December 2016 update for Dynamics 365 (online and on-premises).

Use moveNext to move to the next stage and movePrevious to move to the previous stage. Both of these methods will cause the OnStageChange event to occur.

Progresses to the next stage.

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

Type: Function

Remarks: An optional function to call when the operation is complete. This callback function is passed one of the following string values to indicate whether the operation succeeded.

Value

Description

success

The operation succeeded.

crossEntity

The next stage is for a different entity.

end

The active stage is the last stage of the active path.

invalid

The operation failed because the selected stage isn’t the same as the active stage.

dirtyForm

This value will be returned if the data in the page is not saved.

System_CAPS_importantImportant

This method can only be used when the selected stage and the active stage are the same. When your code is initiated from the OnStageChange event, the current stage will be selected. When your code is initiated from the OnStageSelected event, you should use Xrm.Page.data.process.getActiveStage to verify that the selected stage is also the active stage. For any other form event, it isn’t possible to determine which stage is currently selected. For best results, this method should only be used in code that is called in functions initiated by the OnStageChange and OnStageSelected events.

Moves to the previous stage. You can use movePrevious to a previous stage in a different entity.

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

Type: Function

Remarks: An optional function to call when the operation is complete. This callback function is passed one of the following string values to indicate whether the operation succeeded.

Value

Description

success

The operation succeeded.

crossEntity

The previous stage is for a different entity.

beginning

The active stage is the first stage of the active path.

invalid

The operation failed because the selected stage isn’t the same as the active stage.

dirtyForm

This value will be returned if the data in the page is not saved.

System_CAPS_importantImportant

This method can only be used when the selected stage and the active stage are the same. When your code is initiated from the OnStageChange event, the current stage will be selected. When your code is initiated from the OnStageSelected event, you should use Xrm.Page.data.process.getActiveStage to verify that the selected stage is also the active stage. For any other form event, it isn’t possible to determine which stage is currently selected. For best results, this method should only be used in code that is called in functions initiated by the OnStageChange and OnStageSelected events.

System_CAPS_noteNote

You can use this method to return to a stage for a different entity.

A process contains the data for a business process flow. Use the methods to access properties of the process.

Returns the unique identifier of the process

var processId = procObj.getId();
Return Value

Type:String

Remarks: Value represents the string representation of a GUID value.

Returns the name of the process

var processName = procObj.getName();
Return Value

Type:String

Returns an collection of stages in the process

var stageCollection = procObj.getStages();
Return Value

Type: collection

See Stage methods for the methods to access the properties of the stages returned.

Returns true if the process is rendered, false if not

var processRendered = procObj.isRendered();
Return Value

Type:Boolean

Remarks: If the form used has been upgraded from a previous version of Microsoft Dynamics 365 and has not been upgraded to use new forms, the business process flow control cannot be rendered. More information: TechNet: Update your forms to Microsoft Dynamics CRM 2013 or Microsoft Dynamics CRM Online Fall '13

A process instance contains the data for an instance of the business process flow. Use the methods to access properties of the process instance.

System_CAPS_noteNote

The instance methods were introduced in December 2016 update for Dynamics 365 (online and on-premises).

Returns the unique identifier of the process instance.

Xrm.Page.data.process.getInstanceId();
Return Value

Type:String

Remarks: Value represents the string representation of a GUID value.

Returns the name of the process instance.

Xrm.Page.data.process.getInstanceName();
Return Value

Type:String

Returns the current status of the process instance.

Xrm.Page.data.process.getStatus();
Return Value

Type:String

Remarks: This method will return one of the following values: active, aborted, or finished.

Sets the current status of the active process instance.

Xrm.Page.data.process.setStatus(status, callbackFunction);

Parameters:

status

Type:String

Remarks: The values can be active, aborted, or finished.

callbackFunction

Type:Function

Remarks: An optional function to call when the operation is complete. This callback function is passed the new status as a string value.

A stage contains the data for a stage in a business process flow. Use the methods to access properties of the stage.

Returns an object with a getValue method which will return the integer value of the business process flow category.

var stageCategoryNumber = stageObj.getCategory().getValue();
Return Value

Type:Number

Remarks: See Stage Category (processstage_category) for the list of possible values.

Returns the logical name of the entity associated with the stage.

var stageEntityName = stageObj.getEntityName();
Return Value

Type:String

Returns the unique identifier of the stage

var stageId = stageObj.getId();
Return Value

Type:String

Returns the name of the stage

var stageName = stageObj.getName();
Return Value

Type:String

Returns the status of the stage

var stageStatus = stageObj.getStatus();
Return Value

Type:String

Remarks: This method will return either active or inactive.

Returns a collection of steps in the stage.

var stepsCollection = stageObj.getSteps();
Return Value

Type:Array

See Step methods for methods to access the property values of the step.

A step contains the data for a step in a stage in a business process flow. Use the methods to access properties of the step.

Returns the logical name of the attribute associated to the step.

var stepAttributeName = stepObj.getAttribute();
Return Value

Type:String

Remarks: Some steps don’t contain an attribute value.

Returns the name of the step.

var stepName = stepObj.getName();
Return Value

Type:String

Returns whether the step is required in the business process flow.

var stepIsRequired = stepObj.isRequired();
Return Value

Type:Boolean

Remarks: Returns true if the step is marked as required in the Business Process Flow editor; otherwise, false. There is no connection between this value and the values you can change in the Xrm.Page.data.entity attribute RequiredLevel methods.

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. Copyright

Community Additions

Show: