Applies to: Dynamics 365
Synopsis: This article helps you avoid error “Invalid stage transition. Transition to stage <stage name> is not in the process active path.” by suggesting some best practices for automating stage progression in business process flows.
The Fall 2016 release of Dynamics 365 (version 8.2) introduced big enhancements to business process flows, enabling a number of important customer scenarios (including Concurrent business process flows and Business process flow automation) that we captured on , conferences and community meetups since the introduction of this feature.
In versions of Dynamics 365 prior to the Fall 2016 release (8.1 and prior), organizations that wanted to automate their business processes relied on a few work-arounds, most notably the need to force values on the ProcessID, StageId (active stage) or TraversedPath attributes. Frequently, these techniques would fail with either an error message or a displaying a broken process control. However, there was a small but not fully determined subset of cases where these techniques would appear to work. These techniques would not present obvious visual glitches or error messages, but would typically result in corrupt data in the database. In all of these cases, Microsoft has maintained that programmatically manipulating the business process state is not a supported scenario: neither the front-end web control or the underlying infrastructure have the necessary logic to handle stage skipping, which was not part of the original design.
When talking to customers about the different scenarios in which they wanted to programmatically manipulate business process flows, we identified a few clusters. Below are a few of the most common ones:
In the travel agency scenario, employees had to manually kickstart the booking process and then manually synchronize the business process in Dynamics 365 depending on what happened on the external booking system. Using Dynamics 365 workflows and web services, these manual steps can be automated:
Important: The key rule to keep in mind when modelling successful business processes is that the . The problem with modelling a process as a state machine is that it requires long stage jumps. Often, though, it’s possible to model alternate paths by taking advantage of branching.
For example, consider the Expense Approval process below:
This business process needs to go through 2 levels of approval depending on the total value of the expense. However, if the expense is below the value that requires the second level of approval, the business analyst wishes to skip the 2nd review stage. Instead of using automation to force a future stage, a cleaner implementation leverages branching, such as the following:
Another scenario is the possibility of the expense approval request being denied due to some issue with the information submitted. In this case, the process would have to return to the Review & Submit Request stage from either 1st or 2nd level review stages. There is no way to model a path leading back to a previous stage and the alternative is to leverage automation to navigate back:
The two previous scenarios can be solved in a safe and supported way by taking advantage of the existing functionality in Dynamics 365.The third scenario we want to cover is not a supported scenario, and is currently in this product’s feature backlog. Customers interested in exploring it should vote and add scenarios to this entry on CRM Ideas.
Let’s revisit the travel agency scenario and understand how to automate the forward navigation using different methods in Dynamics 365. The idea is that the process may be on either S3 (Issue Boarding Pass) or S4 (Book Hotel), and we want to automatically advance the process to S5 (Prepare & Send Invoice). While back navigation can jump more than one stage (as long as the new stage is on the traversed path), jumping more than one stage on the forward navigation will cause the aforementioned invalid transition error. The key to automate forward navigation is that the process must explicitly transition to each intermediate stage until the desired stage is reached. For example, if the process is on S3, it must first move to S4 before it moves to S5:
Using Dynamics 365 Workflow, the following logic takes the process forward to the final stage (Prepare & Send Invoice) if it’s on either the third or fourth stages.
As implemented on the designer:
Using the Client API, the moveNext and movePrevious functions manipulate the active stage of the process. They take a callback function with single argument representing the result of the operation.
These functions always apply to the process rendered on the process control. To switch to a different process, call getProcessInstances to get a list of processes associated with the current data record, and pass in the ID of a process instance to the setActiveProcessInstance method to bring it to the foreground.
For more information about these client API methods, see MSDN: Navigation methods and MSDN: ProcessInstance methods
For more information about stage jumping using the server-side C# API, check MSDN: Manage business process flow instances
Existing Business Process Flow automation logic may fail on Dynamics 365 after the upgrade to the Fall 2016 release (from version 8.1 or earlier to version 8.2). This behavior is by design. Most existing automation logic relies on forcing values to the ProcessID, StageId (active stage) or TraversedPath attributes of a data entity, but the Business Process Flow components are not designed to handle arbitrary or long stage jumps like a state machine. Cases that appeared to work on previous versions of Dynamics 365 without visual glitches or error messages, but resulted in corrupt data might fail after the upgrade.
To avoid issues, stage custom solutions and automation logic before committing to the upgrade, using a sandbox environment and making sure to perform a full test pass. It may be necessary to replace stage jump logic with stage-by-stage automation or branches.
Carlos Mendonça | LinkedIn
Senior Program Manager
Dynamics 365 team