Best practices now that the stageid and traversedpath attributes are deprecated on Business Process Flow participating entities

Hi folks,

This blog covers an important change we made in the v8.2 release (Fall 2017 release)

Deprecation of stageid and traversedpath (for participating entities of Business Process Flows)

The traversedpath and stageid attributes on the entities participating in the business process flow (such as Lead or Opportunity) are deprecated and should no longer be used in your customizations. Consult the official documentation to learn more.

You must not read or write to or from these attributes via any extensibility options, such as reporting, custom views, SDKs, plug-ins, OData, client APIs, workflows, etc.

The data in these two deprecated attributes are not always updated or kept consistent with the actual state of the business process flow. If you take a dependency on these deprecated attributes, you will see inconsistent and inaccurate behavior from them.

For example, if you register a plug-in to fire on change of these two attributes, your plug-in would not be guaranteed to fire consistently or fire with the correct values. If you build reports based on the data in these attributes, you may see incorrect information.

Understanding the Business Process Flow backing entity

Starting with v8.2 (Fall 2017 release), each business process flow has a backing entity that’s created in Common Data Service. This backing entity stores the business process flow instance data for your business process.

For example, if I apply the ‘Opportunity Sales Process’ business process flow to one of my opportunity records, a record gets created in the backing entity for the ‘Opportunity Sales Process’. In this case, the backing entity name is OpportunitySalesProcess. The process instance record contains the state of the the current process instance, such as the stage the instance is currently on, the state of the process instance, when it was created, etc.

You can find the name of your business process flow’s backing entity name in the business process flow designer when you open your process definition and select the ‘^’ icon at the top of the page to expand details:

Consume the ‘ActiveStageId’ and ‘TraversedPath’ attribute on the backing Business Process Flow entity

Every backing entity contains the ‘ActiveStageId’ and ‘TraversedPath’ attributes. These two attributes store the guid for the stage the process instance is on, and the comma separated list of the guids of all the stages the process instance has traversed, respectively. These are the two supported attributes on which you should build extensibility and customizations if you want information around the current stage or traversed path for the process instance. These two attributes are always updated with the correct data.

Please see the below documentation for additional details around consuming business process flow attributes: https://docs.microsoft.com/flow/best-practices-entity-attributes

If you have any additional questions around the use of these two attributes, please leave a comment on this blog and we will get back to you with a response.

Note: this blog article applies to v8.2 and above.

Thanks,

Hampton Terry

Senior Software Developer

Microsoft Flow / Business Process Flow team