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.

With the introduction of the Fall 2016 release and all the new functionality for business processes, some of the work-around technique cases that appeared to work might now present visual glitches or error message “Invalid stage transition. Transition to stage <stage name> is not in the process active path.” when they fail. The good news is that one of the important changes introduced to business processes is support for automation and programmability scenarios. Since business processes are now represented as Dynamics 365 entities (with lookups to the participating data entities), they can be manipulated through Dynamics 365 workflows or programmatically through either the JavaScript Client API or the OData (REST) Web API. This post explores some scenarios and how they should be handled in a safe and supported way.

Scenarios

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:

1. Parts of the business process run on Dynamics 365 while others run on another system, in parallel, and the organization would like to keep them in sync
   For example, a travel agency collects customer information on Dynamics 365, issues reservations on a proprietary system, and submits the invoice back on Dynamics 365

2. Erratic business process with lots of exception conditions
   For example, flows that force the jump of the process to a future or past stage
3. Data migration
   For example, organizations that had business processes modelled on a third-party system and now would like to migrate them in bulk to Dynamics 365

Parallel systems

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:

• First, a Dynamics 365 on-demand workflow on the Opportunity entity calls a custom plugin written in C# that, in turn, issues a web service request to start the booking process on the external booking system. The on-demand workflow is configured to trigger either on exit of the Capture Trip Information stage or on entry of the Issue Boarding Pass stage—in this case, they’re equivalent
• Next, the external booking system has to make an UPDATE request to business process entity and change the value of the Active Stage from Issue Boarding Pass to Book Hotel. Changing the value of the stage to one ahead in the active path, or one or more behind in the traversed path, is considered a valid transition. When this transition occurs, the StageId (active stage) and TraversedPath attributes are updated along with the internal entities and fields that participate of the process, which maintains data consistency. A similar operation is performed to transition from Book Hotel to Prepare & Send Invoice

Erratic flow

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 2^nd 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 1^st or 2^nd 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:

Data migration

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.

Programmatic stage jumping

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:

With Dynamics 365 workflows

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:

With Client API

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

Stage jumping writing a C#-based plug-in

For more information about stage jumping using the server-side C# API, check MSDN: Manage business process flow instances

Conclusion

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