Programming business process flows in Dynamics 365 V9.


Microsoft has introduced new way how to operate with business process stages. Previously we used several fields placed directly on the entity which are using business process flow. Now in Dynamics 365 V9, there is a special entity for every business process which handles all information about active process stage and other important information.  In this article, we will review the architecture of business process flows and new SDK messages which could help us to cover complex scenarios easier.

Let’s first understand how business process flows are works. Let’s review the standard business process flow called “Opportunity Sales Process”. For this processes system contains special entity called “opportunitysalesprocess”. Once you create a new instance of opportunity which uses “Opportunity Sales Process”, then also a new instance of opportunitysaleprocess will be created to handle in which phase are you in your sales process. For example, if you try to copy standard “Opportunity Sales Process” and create a new one the system will automatically create an entity for you to handle your new sales process. You can see a newly created business process flow on the picture below:


As you see the attribute Name actually contains the name of the newly created entity, which will handle all activities regarding this business process flow. However, you can get a more friendly logical name from the SDK. This entity will be created once you activate business process flow. The next step is to create an opportunity which will use this business process flow, this operation will cause the creation of entity instance which you could easily retrieve through SDK. To retrieve business process flow information from concrete opportunity you need to launch following code:

var query = new QueryByAttribute("opportunitysalesprocess(copy)")
    ColumnSet = new ColumnSet(true)
query.AddAttributeValue("bpf_opportunityid", new Guid("OpportunityId"));
var bpf = _serviceProxy.RetrieveMultiple(query).Entities.FirstOrDefault();

As we know the name of our business process flow and the opportunity id we can easily get all information about the concrete business process.

On the picture below you can see all the attributes of the entity:

As you can see there is a field called activestageid which represent current stage of the business process flow. This field is a reference to the entity called processstage. You can change this field through the SDK and it is a fully supported way. This entity you could also retrieve using standard SDK messages. In case you need to retrieve all available business process stages for the business process flow or business process flow description for the concrete opportunity, there are two new SDK messages for it. Let’s review SDK Message RetrieveProcessInstanceRequest.

RetrieveProcessInstancesRequest procRequest = new RetrieveProcessInstancesRequest
                        EntityId = new Guid("Opportunity Id"),
                        EntityLogicalName = Opportunity.EntityLogicalName
RetrieveProcessInstancesResponse procResp = (RetrieveProcessInstancesResponse)_serviceProxy.Execute(procRequest);

Above code should return all existing business process flows for the opportunity. The first record is always active business process flow instance.  It returns the result like in the picture below:


Attributes from this message a bit different from fields we got directly from the entity. According to documentation processstageid field represents id of the active stage. Attribute name returns entity logical name. As you have information about active business process flow it is now much easier to handle complex cases when, for example, you need to manage several business processes with different stages and logic for one entity.

The second SDK message called RetrieveActivePathRequest. You should provide Busines Process Flow Id as an input argument to this message and it will return all possible stages of this business process flow. Please find the code snippet below.

var activeProcessInstance = procResp.Processes.Entities[0].Id;
RetrieveActivePathRequest pathReq = new RetrieveActivePathRequest
                 ProcessInstanceId = activeProcessInstance
RetrieveActivePathResponse pathResp = (RetrieveActivePathResponse)_serviceProxy.Execute(pathReq); 

Here is how the results look like:


To change active stage of business process flow you just need to update field activestageid of the appropriate business process flow entity.

It is also very important that business process flows are really good integrated together with workflows so that you can perform lots of operations without any piece of code. You can add workflow directly to the business process flows or just use them to change the active stage. I would personally recommend following articles which might help you to better understand available functionality:

Articles to read:

Leave a Reply