Opportunities: Stage, Pipelines and Phases

As Dynamics has evolved, the way to determine the stage of an opportunity has changed. There are three periods to consider:

  • before Business process flows were introduced (CRM 2011 and earlier)
  • Introduction of Business process flows (with only one flow per record) (CRM 2013 to 2016 version 8.1)
  • Business process flows in their own entity (allowing muliple flows per record)  (365 version 8.2 onwards)

After business process flows were changed to use their own entities, you can no longer rely on fields in an opportunity record because there might be multiple business process flows operating on the record.

If you use multiple business process flows for an oppportunity then to determine the stage, you need to use fields from the relevant business process flow.

Fields to do with Stages for Opportunity

Field (Display Name) Field (Schema Name) Field type Purpose
Pipeline Phase stepname Text

This field is automatically populated by Dynamics 365 to the value of the Stage Category associated with the current Stage in the associated busines process flow.

The Stage Category is prefixed with an integer that represents the display order of the Stage Category in the Stage Category global option set.

Since more than one business process flow can be applied to a record, I don't see that this field is useful for reporting.

Process processid GUID

The GUID of the associated business process flow.

But, how does this work if there is more than business process flow started for a record? It seems that processid is set to the most recent business process flow to be started for a record and does not change if a user switches to another already started business process flow.

Since more than one business process flow can be applied to a record, this field is not useful for reporting.

Process Code salestagecode Option Set (local)

Microsoft definition: "Select the sales process stage for the opportunity to indicate the probability of closing the opportunity."

By default, option set has a single option named "Default Value".

Process Stage stageid GUID

The GUID of the active stage in the associated business process flow. It seems that stageid is updated whenever a user changes the active stage in any business process flow that has been applied to the record.

To show the name of the stage in a view you need to select the Process Stage Name field from the parent Process Stage entity.

But since more than one business process flow can be applied to a record, this field is not particularly useful for reporting.

Sales Stage salesstage Option Set (global)

Microsoft description: "Select the sales stage of this opportunity to aid the sales team in their efforts to win this opportunity". Default values are: Qualify, Develop, Propose and Close

This field predates business process flows and should not be used if you use business process flows.

Step stepid GUID

Microsoft description: "Shows the ID of the workflow step"

Not sure what this means, I have not seen values in this field.

Reporting by Business Process Flow

To see the active stage for a specific business process flow associated with an opportunity, create an Advanced Find on the entity that represents the business process flow and add the Active Stage column. You can also add fields from the Opportunity and the Stage category from Process Stage.

I noticed that for the out of the box Lead to Opportuntiy Sales Process  business process, the label for the active stage field is Active Stage Id but for custom business process flows the label is Active Stage.

Single Business Process Flow for Opportunity

If your system is configured to only use one business process flow you could consider using the processid and stageid fields on Opportunity but it wouldn't surprise me if these fields are eventually removed so I suggest that you get used to using the business process flow entities.

Other Relevant tables

Table Purpose
processtage Stores a row for each stage in every business process flow. For example, if a business process flow has three stages then there will be three rows in this table.
workflow Stores definition of a business process flow
new_bpfname An entity is created for every activated business process flow. This entity stores a
businessprocessflowinstance Contains a row for every instance of a business process flow that has been started against a record

Business Process Flows

Each user can select which business process flow to apply to a record.

This means that more than one business process flow can apply to a record at at the same time. Each user, can start more than one business process flow and switch between them. However, for any given user, only one business process flow can be shown on the form.

Only one instance of a specific business process flow can be applied to a record - so it is not possible for two users to both start their own instance of the same business process flow; each would see the business process flow at the same stage with the same values for steps.

This article https://blogs.msdn.microsoft.com/crm/2017/07/30/how-to-determine-which-business-process-flow-bpf-instance-is-shown-when-a-record-is-opened-2/ describes how Dynamics determines which business process flow to show on a form when a user opens a record. In case this article disappears, I've reproduced the relevant part here:

When a record associated with a BPF is opened in the Dynamics 365 app, the system uses a selection algorithm to look for all actively running instance in the Read Only business process instance entity table. This table is also the intersect table for all BPFs in the system. The record may be part of the primary entity on the BPF, or one of the participating entities in the flow. Participating entities are the entities present in the BPF that are different than the entity of the first stage. The algorithm then filters the returned entity collection by user permission and sorts in descending order by the value of the [word missing, business process flow order?]

Additional complexity is introduced in the case where there are multiple users updating the same record using the same BPF. When the record is reopened or updated again the BPF displayed on the record may be different than the previous access or update to the record. To maintain the user selection, the system uses a user-specific cache that keeps track of the BPF instance selection per record. The selection persistence is temporary. It is used to ensure that the user selection does not change within the same session. In a limited manner, it is also persisted across sessions so that if the user opens the same record the selection is remembered. More specifically, the system uses the same Most Recently Used (MRU) cache to keep track of user selection and holds up to 40 user selections, for example record to BPF instances. 

 

 

Review: