Udostępnij za pośrednictwem

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

  • Artykuł

 

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.

Xrm.Page.data.process methods

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

ActiveProcess methods

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.

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.

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.

Note

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

getProcessInstances

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.

setActiveProcessInstance

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.

ActiveStage methods

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.

Note

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.

    Important

    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.

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.

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.

getEnabledProcesses

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.

getSelectedStage

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.

Methods to manage event handlers

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.

addOnProcessStatusChange

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

removeOnProcessStatusChange

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.

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.

Important

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

Important

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.

Note

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

Process methods

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();

Instance methods

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

Note

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

getInstanceId

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.

getInstanceName

Returns the name of the process instance.

Xrm.Page.data.process.getInstanceName();
  • Return Value
    Type:String

getStatus

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.

setStatus

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.

Stage methods

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();

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.

Step methods

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.

See Also

Write scripts for business process flows
Xrm.Page.ui.process (client-side reference)
Client-side programming reference
Form scripting quick reference
Write code for Microsoft Dynamics 365 forms
Use the Xrm.Page object model
Sample: Xrm.Page.data.process.getEnabledProcesses
Sample: Xrm.Page.data.process.getActivePath

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. Copyright