Model business process flows

Article
09/19/2017

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

A business process flow lets you create more efficient and streamlined sales, service, and other business processes. Having high performing processes in place will help you to increase your win rates, improve customer satisfaction, and grow your revenue.

A business process flow creates a visualization of your business process by placing special controls at the top of the entity forms. Users are guided through various stages of sales, marketing, or service processes towards completion. Each process supports multiple stages and steps. You can add or remove steps, change the order of stages, or add new entities to the business process flow.

With December 2016 update for Dynamics 365 (online and on-premises), different business process flow definitions can be associated with different roles and the instances can run concurrently against the same entity record. Users can switch between concurrent business process instances and resume their work at a current stage in the process. The new visual drag-and-drop process designer allows creating processes, such as business process flows and task flows, as well as business rules, using an intuitive graphical interface in Dynamics 365.

For detailed information about processes, see TechNet: Business Process Flows

In This Topic

Server-side programmability support for business process flow

Client-side programmability support for business process flows

Maximum number of processes, stages, and steps

Server-side programmability support for business process flow

A business process flow definition is stored in the Workflow entity. Business process flow is one of the categories of the process. Other process categories include action, workflow, and dialog. For more information, see Dynamics 365 Process categories. Custom entities and entities that have updated UI forms can participate in the business process flow. The updated UI entities have the IsAIRUpdated property set to true. To enable an entity for the business process flow, set the IsBusinessProcessEnabled property to true.

Important

Enabling an entity for business process flow is a one way process. You can’t reverse it.

Define business process flow
Activate business process flow
Manage security for business process flows
Manage business process flow instances
Apply business process flow while creating an entity record

Define business process flow

Use the new visual business process flow designer in Dynamics 365 to define a business process flow. The Workflow entity stores a business process flow definition, and the following attribute values must be specified in the Workflow entity record for a business process flow: name, category, businessprocesstype, primaryentity, uniquename, and xaml. For information about these attributes, see workflow EntityType. By default, a business process flow record is created in the Draft state.

Activate business process flow

Before you can use the process flow, you have to activate it. To activate it, you must have the prvActivateBusinessProcessFlow privilege for the Workflow entity. Use the UpdateRequest message to set the state of the Workflow entity record to Activated. More information: Perform specialized operations using Update

Once you activate a business process flow definition (by changing the state of the corresponding Workflow entity record), a custom entity with the following name is automatically created to store the activated business process flow instances: "<activesolutionprefix>_<uniquename>".

For example, if you specified unique name of the business process flow definition as "myuniquebpf1" and are using the default publisher for your active solution, the name of the custom entity created for storing process instances will be "new_myuniquebpf1".

If the uniquename value isn't available for a business process flow definition, for example if the business process flow was imported as part of solution from an earlier version, the default name of the custom entity will be "<activesolutionprefix>_bpf_<GUID_BPF_Definition>:

Important

The sample business process flow records available in Dynamics 365 use system entities to store the corresponding business process flow instance records. Couple of the sample business process flow entity records are opportunitysalesprocess EntityType and leadtoopportunitysalesprocess EntityType.

However, any new business process flow definitions you create will use custom entities to store its instance records as explained earlier.

Manage security for business process flows

The custom entity that is automatically created on activating a business process flow to store business process flow instances adheres to the standard security model as for any other custom entity in Customer Engagement. This implies that privileges granted on these entities define the runtime permissions for users for business process flows.

The custom business process flow entity has organization scope. The regular create, retrieve, update and delete privileges on this entity define the permission the user would have based on his/her assigned roles. By default, when the business process flow custom entity is created, only system administrator and system customizer security roles are granted access to it, and you must explicitly grant permissions to this custom entity for other security roles as required.

Manage business process flow instances

The custom entity that is automatically created on activating a business process flow definition stores all the process instances for the business process flow definition. The custom entity supports programmatic creation and management of records (process instances) using Web API and CRM 2011 endpoint. For example, if the name of the custom entity is "new_myuniquebpf1", you can use the following Web API query to retrieve all the records (process instances) in the custom entity:

[Organization URI]/api/data/v8.2/new_myuniquebpf1s

A process instance can have one of the following states: Active, Finished, or Aborted.

Important

This section provides information about programmatically managing various business process flow scenarios such as switching business processes, retrieving process instances for an entity record, retrieving active path and active stage for a process instance, and moving to next or previous stage. You must use the messages and appropriate business process flow entity/entities as described in this section to programmatically manage and automate your business process flows.

Manipulating process related attributes (such as ProcessId, StageId, and TraversedPath) on entities enabled for business process flows does not guarantee consistency of the business process flow state, and is not a supported scenario. The only exception to this is programmatically modifying the ProcessId attribute while creating an entity record to override the default application of the business process flow to the new record. More information: Apply business process flow while creating an entity record

Use the SetProcess Action or SetProcessRequest message to set another business process flow as the active process instance for the target entity record. An active process instance is the one that is visible on the UI for the entity record. If there isn't any process instance of the specified business process flow definition, a new business process flow instance will be created, and set as active for the entity record. If there is already a process instance of the business process flow definition, the process instance will be set as the active process instance for the entity record. If you want to set a particular process instance as the active process instance for an entity record, you can use the NewProcessInstance property to specify the instance.

Setting an active process programmatically is the same as switching to another process instance for the entity record in UI. Since each business process flow instance maintains its own stage and step progress information, switching to another business process instance does not cause you to lose the progress information, and you resume from the same point where you were last time.

The following sample code demonstrates how you can switch to another business process flow for an entity record:

SetProcessRequest setProcReq = new SetProcessRequest
{
    Target = new EntityReference(Opportunity.EntityLogicalName, _opportunityId),
    NewProcess = new EntityReference(Workflow.EntityLogicalName, _bpfId)
};
SetProcessResponse setProcResp = (SetProcessResponse)_serviceProxy.Execute(setProcReq);

In the above code sample, the _bpfId variable represents the ID of the business process flow definition that you want to switch to; you can retrieve the ID of the required business process flow definition by querying the Workflow entity. The following sample code demonstrates how you can retrieve the ID of the sample "Opportunity Sales Process" business process flow definition by querying the Workflow entity:

QueryExpression opportunityBpfQuery = new QueryExpression
{
    EntityName = "workflow",
    ColumnSet =  new ColumnSet("name"),
    Criteria = new FilterExpression
    {
        Conditions =
        {
            new ConditionExpression
            {
                AttributeName = "uniquename",
                Operator = ConditionOperator.Equal,
                Values = { "opportunitysalesprocess" }
            }
        }
    }
};
Workflow retrievedBPF = (Workflow)_serviceProxy.RetrieveMultiple(opportunityBpfQuery).Entities[0];
_bpfId = retrievedBPF.Id;

For the complete sample, see Sample: Work with business process flows

Use the RetrieveProcessInstances Function or the RetrieveProcessInstancesRequest message to retrieve all the business process flow instances for an entity record across all business process definitions. The business process flow instances returned for an entity are ordered based on the modifiedon attribute for the instance. For example, the most recently modified business process flow instance will be the first record in the returned collection. The most recently modified business process flow instance is the one that is active on the UI for an entity record.

The following sample code demonstrates how to retrieve business process flow instances for an entity record, and then lists the process instances associated with the entity record:

RetrieveProcessInstancesRequest procOpp2Req = new RetrieveProcessInstancesRequest
{
    EntityId = _opportunityId,
    EntityLogicalName = Opportunity.EntityLogicalName
};

RetrieveProcessInstancesResponse procOpp2Resp = (RetrieveProcessInstancesResponse)_serviceProxy.Execute(procOpp2Req);

// Declare variables to store values returned in response
int processCount = procOpp2Resp.Processes.Entities.Count;
var activeProcessInstance = procOpp2Resp.Processes.Entities[0]; // First record is the active process instance
_processOpp2Id = activeProcessInstance.Id; // Id of the active process instance, which will be used
                                           // later to retrieve the active path of the process instance

if (processCount > 0)
{
    // Display the count of process instances concurrently associated with the opportunity record
    Console.WriteLine("\nCount of process instances for the opportunity record: {0}", processCount);

    // Display all the process instances associated with the opportunity record
    // Demonstrates that multiple processes can run concurrently against the same record
    Console.WriteLine("\nProcess instances associated with the opportunity record:");
    for (int i = 0; i<processCount; i++)
    {
        Console.WriteLine("\t{0}", procOpp2Resp.Processes.Entities[i].Attributes["name"]);
    }
}

The returned business process flow instance records for an entity record also store the ID of the active stage in the processstageid attribute that can be used to find the active stage, and then move to the previous or next stage. To do so, you first need to find the active path of a business process flow instance and the stages available in the process flow instance using the RetrieveActivePath Function or RetrieveActivePathRequest. The following sample code demonstrates how to retrieve the process stages in the active path for a business process flow instance and the active stage of the instance:

// Retrieve the active stage ID of in the active process instance
_activeStageId = new Guid(activeProcessInstance.Attributes["processstageid"].ToString());

// Retrieve the process stages in the active path of the current process instance
RetrieveActivePathRequest pathReq = new RetrieveActivePathRequest
{
    ProcessInstanceId = _processOpp2Id
};
RetrieveActivePathResponse pathResp = (RetrieveActivePathResponse)_serviceProxy.Execute(pathReq);

Console.WriteLine("\nRetrieved stages in the active path of the process instance:");
for (int i = 0; i <pathResp.ProcessStages.Entities.Count; i++)
{
    Console.WriteLine("\tStage {0}: {1} (StageId: {2})", i + 1,
                            pathResp.ProcessStages.Entities[i].Attributes["stagename"], 
                            pathResp.ProcessStages.Entities[i].Attributes["processstageid"]);

    // Retrieve the active stage name and active stage position based on the activeStageId for the process instance
    if (pathResp.ProcessStages.Entities[i].Attributes["processstageid"].ToString() == _activeStageId.ToString())
    {
        _activeStageName = pathResp.ProcessStages.Entities[i].Attributes["stagename"].ToString();
        _activeStagePosition = i;
    }
}

// Display the active stage name and Id
Console.WriteLine("\nActive stage for the process instance: {0} (StageID: {1})", _activeStageName, _activeStageId);

Once you have the active stage and the active path information for a business process flow instance, you can use the information to move to a previous or next stage in the active path. Forward navigation of stages must be done in sequence, that is, you should only move forward to the next stage in the active path. The following sample code demonstrates how to move to the next stage for a business process flow instance:

// Retrieve the stage ID of the next stage that you want to set as active
_activeStageId = (Guid)pathResp.ProcessStages.Entities[_activeStagePosition + 1].Attributes["processstageid"];

// Retrieve the process instance record to update its active stage
ColumnSet cols1 = new ColumnSet();
cols1.AddColumn("activestageid");
Entity retrievedProcessInstance = _serviceProxy.Retrieve("opportunitysalesprocess", _processOpp2Id, cols1);

// Set the next stage as the active stage
retrievedProcessInstance["activestageid"] = new EntityReference(ProcessStage.EntityLogicalName, _activeStageId);
_serviceProxy.Update(retrievedProcessInstance);

For the complete sample, see Sample: Work with business process flows.

Apply business process flow while creating an entity record

This section provides information about the default behavior for applying business process flows automatically to new entity records created in Customer Engagement, and how you can override it to apply a business process flow of your choice for new entity records.

By default, for an entity that has multiple business process flows defined for it, the system applies a business process flow to the new entity record using the following multi-step logic:

Identify all business process flows applicable to the new entity record based on the Workflow.PrimaryEntity attribute of the business process flow definition records.
Identify the business process flow definitions that the current user has access to. For information about how access to a business process flow is determined and managed, see Manage security for business process flows earlier in this topic.
All business process flow definitions in the system are subject to a global order per entity. The order of the business process flow is stored in the Workflow.ProcessOrder attribute. The business process flow definitions for an entity are sorted based on this order, and the one with the least order value is picked.
Finally, if the entity record is created from a business app (app module), one more level of filtering is applied to pick the business process flow to be applied automatically to the new entity record. When working in an app, users can access only relevant entities, business process flows, views and forms that they have access to by virtue of the security roles assigned to the business app.
- If the business app does not contain any business process flow then business process flow is applied as explained until step 3.
- If the business app has one or more business process flows then only the business process flows present in the app would be applicable. In this case, when the user is working within a business app context, the list of business process flows from step 3 are filtered further to the ones that are part of the business app that are present inside the app module, and are sorted based on the process order.
- If no business process flow is available in a business app for the entity or one that the user has access to then no business process flow is applied for the new entity record.

You can override the default behavior of business process flows getting applied automatically to new entity records. To do so, set the ProcessId attribute of the entity to one of the following values while creating a new entity record:

Set to Guid.Empty to skip setting a business process flow for new entity records. You might want to do that if you are bulk creating entity records, but don't want business process flow to be applied to them.
Set it to a specific business process flow entity (as an entity reference). In this case, the system will apply the specified business process flow instead of the default logic.

If you do not set a value for the ProcessId attribute while creating a new entity record, the system will apply the default logic as explained earlier.

Note

Overriding the default behavior of business process flows getting applied automatically to new entity records is only supported programmatically. You cannot do this using the UI.

Client-side programmability support for business process flows

With Dynamics 365 there is a client-side object you can use to interact with business process flows in your form scripts. Business process flows trigger client-side events every time a process is either applied to a record, the stage is changed, or its status is changed to Active, Finished, or Aborted. More information: Write scripts for business process flows

Maximum number of processes, stages, and steps

Per entity, the default value for the maximum number of activated business process flows is 10. You can specify a different value by using the Organization.MaximumActiveBusinessProcessFlowsAllowedPerEntity attribute. However, if the value is greater than 10, you may see a decrease in your system’s performance when you switch processes or open a record that has an assigned business process flow. This may be especially noticeable if processes span multiple entities.

The following settings aren’t customizable:

The maximum number of stages per entity in the process is 30.
The maximum number of steps in each stage is 30.
The maximum number of entities that can participate in the process flow is 5.

Model business process flows

In This Topic

Server-side programmability support for business process flow

Define business process flow

Activate business process flow

Manage security for business process flows

Manage business process flow instances

Apply business process flow while creating an entity record

Client-side programmability support for business process flows

Maximum number of processes, stages, and steps

See Also

Additional resources