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

Applies To: CRM 2015 on-prem, CRM Online

With Microsoft Dynamics CRM 2015 dan Microsoft Dynamics CRM Online 2015 Kemaskini, 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
Use getActiveProcess to retrieve information about the active process and setActiveProcess to set a different process as the active process.

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

With Kemas Kini 1 Microsoft Dynamics CRM Online 2015 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
Added with Kemas Kini 1 Microsoft Dynamics CRM Online 2015, use this method to access the currently selected stage.

Methods to manage event handlers
Use the addOnStageChange, removeOnStageChange, addOnStageSelected, and removeOnStageSelected 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.

With Kemas Kini 1 Microsoft Dynamics CRM Online 2015 you can use movePrevious to a previous stage in a different entity.

Process methods
Use process methods to access properties of the process.

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.

getActiveProcess

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.

setActiveProcess

Set a Process as the active process.

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 getActiveStage to retrieve information about the active stage and setActiveStage to set a different stage as the active stage.

getActiveStage

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.

setActiveStage

Set a completed stage as the active stage.

noteNota
With Kemas Kini 1 Microsoft Dynamics CRM Online 2015 you can use this method to 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

crossEntity

The stage must be one for the current entity.

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.

ImportantPenting
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
This method was added for Kemas Kini 1 Microsoft Dynamics CRM Online 2015

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.

addOnStageChange

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.

removeOnStageChange

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.

addOnStageSelected

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.

removeOnStageSelected

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 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.

moveNext

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.

ImportantPenting
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.

movePrevious

Moves to the previous stage. With Kemas Kini 1 Microsoft Dynamics CRM Online 2015 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.

ImportantPenting
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.

noteNota
With Kemas Kini 1 Microsoft Dynamics CRM Online 2015 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.

getId

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.

getName

Returns the name of the process

var processName = procObj.getName();
Return Value
Type: String

getStages

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.

isRendered

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 CRM and has not been upgraded to use new forms, the business process flow control cannot be rendered. Maklumat lanjut: TechNet: Update your forms to Microsoft Dynamics CRM 2013 or Microsoft Dynamics CRM Online Fall '13

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

getCategory

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.

getEntityName

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

var stageEntityName = stageObj.getEntityName();
Return Value
Type: String

getId

Returns the unique identifier of the stage

var stageId = stageObj.getId();
Return Value
Type: String

getName

Returns the name of the stage

var stageName = stageObj.getName();
Return Value
Type: String

getStatus

Returns the status of the stage

var stageStatus = stageObj.getStatus();
Return Value
Type: String

Remarks: This method will return either active or inactive.

getSteps

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.

getAttribute

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.

getName

Returns the name of the step.

var stepName = stepObj.getName();
Return Value
Type: String

isRequired

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 CRM 2015 and Microsoft Dynamics CRM Online
Send comments about this topic to Microsoft.
© 2015 Microsoft. All rights reserved.
Tunjukkan: