Preview Custom Controls in Business Process Flows

[Karan_MSFT]

Business process flows (BPF) provide a guided way to get work done in the form of stages and steps. Stages tell you where you are in the process, while steps are action items that lead to a desired outcome. Steps in a business process are bound to fields in the Common Data Service (CDS), and until now, only allowed for default visualizations of the field type (text boxes, dropdowns, and so on.)

With this preview, you will be able to use custom controls to add rich visualizations (such as sliders, radial knobs, the LinkedIn control, and more) to BPF steps and deliver engaging experiences to users of your business process.

Adding custom controls to a business process

Let’s say that you’d like to add a radial knob for the ‘Estimated Budget’ step and a flip switch for the ‘Identify Decision Maker’ step of the Lead to Opportunity Sales process. 

In this version of the preview, we’ll do this by:

1. Configuring custom controls on a related entity form
2. Generating and exporting the BPF form
3. Copying custom control configurations to the BPF form from the related entity form
4. Importing our customizations back into the CDS environment

Step 1: Configure custom controls on a related entity form

In this version of the preview, the easiest way to add custom controls to a BPF is to begin by adding them to a form of the entity that the BPF stage is defined on.

In our example, the Budget Amount and Decision Maker steps of the Qualify stage are defined on the Lead entity. We begin by adding these fields to the Lead main form, and then configure the radial knob and flip switch custom controls for them.

Not familiar with configuring custom controls? Here's a primer to get you started

Step 2: Generate and export the BPF form

To generate the form for a business process you want to add custom controls to, open the business process in the BPF designer and click on Activate/Update.

Activating/updating a BPFActivating/updating a BPF

Once generated, export the form for this BPF in a solution. To do this:

1. Navigate to http://web.powerapps.com, click on ‘Solutions’ and then click ‘New solution’

   Creating a new solutionCreating a new solution

2. Give the solution a name, select a publisher for it, and give it a version number. Finally, click on the save button to create the solution

   Saving a solutionSaving a solution

3. Now that we’ve created a solution, let’s add those BPFs to it that that we want to add custom controls for. Begin by clicking ‘Processes’ in the pane on the left, and then click ‘Add Existing’

   Adding a business process to a solutionAdding a business process to a solution

4. In the dialog that appears, select the BPFs that you’d like to add custom controls to, and then click OK. In this example, we pick the Lead to Opportunity Sales Process

   

5. Next, click save, and then click ‘Export Solution’ to export the BPF along with its form.

   Exporting a solutionExporting a solution

6. In the solution export wizard that appears, first click ‘Publish All Customizations’. Doing so makes sure you’re exporting the latest version of your BPF. Once customizations are published, click ‘Next’

   

   On the 2nd page of the wizard, click ‘Next’

   

   On the 3rd page of the wizard, click ‘Managed’. Finally, click on ‘Export’ to download your solution as a .zip file.

   

7. Similarly, export the Lead entity main form using a managed solution. We'll need this to copy the custom control configurations from
8. Finally, go back to the solutions tab in the PowerApps portal and delete the solutions that we just exported. This will ensure we’re able to import our updated solution containing custom controls in the BPF back into the CDS environment

   Deleting a solutionDeleting a solution

Step 3: Copy custom control configurations to the BPF FormXML

To add custom controls to the BPF, we begin by copying the custom control configurations from the Lead entity form that we just exported. To do this, we begin by viewing the FormXML for the Lead entity form, which can be found in the 'customizations' file in the solution zip file.

1. To locate the custom control configuration we need to copy, begin by searching this document to locate a <control> tag where its datafieldname attribute is the name of the field in CDS (in our example, these are budgetamount and decisionmaker)
2. Make a note of the uniqueid attribute valueLocating the uniqueid for controlsLocating the uniqueid for controls
3. Next, search the document for a <controlDescription> tag where its forControl attribute value matches the uniqueid attribute value of the <control> tag that we took a note of
4. All the content within the <controlDescription>...</controlDescription> tags is the definition of the custom control. Custom control definitions in the lead formCustom control definitions in the lead form

Next, we'll paste these custom control definitions into the FormXML of the BPF from we exported in Step 2. Just as before, this can be found in the customizations file in the solution zip file that contains the BPF

To add custom controls in this document:

1. Locate the FormXML for the ‘Lead to Opportunity Sales Process’ entityLocating the BPF FormXMLLocating the BPF FormXML
2. In the FormXML, each tab maps to a stage in the business process, and each cell within a tab maps to a step in that stage of the business process. Since our steps are in the 1st stage of the BPF, we’re going to look to add custom controls to the cells in the 1st tabIdentifying stages in the BPFIdentifying stages in the BPF
3. In the tab for the Qualify stage of the Lead to Opportunity Sales Process in the FormXML, locate the controls for Estimated Budget and Identify Decision Maker fields by their field names(budgetamount and decisionmaker respectively) in the datafieldname attribute of the <control>tagIdentifying steps in a BPF stageIdentifying steps in a BPF stage
4. For each control, add a uniqueid attribute to help uniquely identify that control for the step and set its value to that in the lead form.Pasting the uniqueid for stepsPasting the uniqueid for steps
5. Next, add the following right before the </form> end tag

   <controlDescriptions>
   </controlDescriptions>

6. Finally, paste the <controlDescription> content (copied from the Lead form) within the <controlDescriptions> tag and save the file.
7. For our example, the custom control descriptions should look something like below:

   <controlDescriptions>
         <!-- Custom control config. for Est. budget step copied from the lead form -->
         <controlDescription forControl="{2aab7103-b2d2-b51e-82b0-546216127825}"> 
              <customControl formFactor="0" name="MscrmControls.Knob.ArcKnobControl">
                   <parameters>
                        <value>budgetamount</value>
                        <min static="true" type="Whole.None">0</min>
                        <max static="true" type="Whole.None">1000000</max>
                        <step static="true" type="Whole.None">10</step>
                   </parameters>
              </customControl>
              <customControl formFactor="1" name="MscrmControls.Knob.ArcKnobControl">
                   <parameters>
                        <value>budgetamount</value>
                        <min static="true" type="Whole.None">0</min>
                        <max static="true" type="Whole.None">1000000</max>
                        <step static="true" type="Whole.None">10</step>
                   </parameters>
              </customControl>
              <customControl formFactor="2" name="MscrmControls.Knob.ArcKnobControl">
                   <parameters>
                        <value>budgetamount</value>
                        <min static="true" type="Whole.None">0</min>
                        <max static="true" type="Whole.None">1000000</max>
                        <step static="true" type="Whole.None">10</step>
                   </parameters>
              </customControl>
         </controlDescription>
         <!--Custom control config. for decision maker step copied from the lead form-->
         <controlDescription forControl="{b4c7a6d3-ad2b-a237-cb4e-5b62178b1762}"> 
              <customControl formFactor="0" name="MscrmControls.FlipSwitch.FlipSwitchControl">
                   <parameters>
                        <value>decisionmaker</value>
                   </parameters>
              </customControl>
              <customControl formFactor="1" name="MscrmControls.FlipSwitch.FlipSwitchControl">
                   <parameters>
                        <value>decisionmaker</value>
                   </parameters>
              </customControl>
              <customControl formFactor="2" name="MscrmControls.FlipSwitch.FlipSwitchControl">
                   <parameters>
                        <value>decisionmaker</value>
                   </parameters>
              </customControl>
         </controlDescription>
   </controlDescriptions>

Step 4: Import customizations into the CDS environment

1. Now that we’re done making our changes, save the customizations.xml document and add it to the managed solution zip file containing the BPF, replacing the file within it.
2. Next, import these changes into your CDS environment by going to the Solutions tab in the PowerApps portal and click ‘Import’.

   Importing a solution into a CDS environmentImporting a solution into a CDS environment

   In the dialog that appears, pick the managed solution that we’ve added the edited customizations.xml document to, click ‘Next’ and then click ‘Import’ on the subsequent screen.

3. Once import is complete, click on ‘Publish all customizations’ to apply the custom controls to the business process

   Publishing customizationsPublishing customizations

And we’re done! Create or resume an instance of the Lead to Opportunity Sales Process in any model driven app to see the custom controls in the Qualify stage.

Things to keep in mind

1. Custom controls are only available in model driven apps and will not be displayed in the legacy (web client) UI
2. If there are any errors in the formXML for the BPF, the BPF step will fall back to using the default rendering instead of using the custom control

Thanks for Reading!!

[Anonymous]

 Hello @Karan_MSFT ,

is this procedure still working? Since three weeks ago I've been having problems with this control. It won't work on BPF until you expand the window. It used to work fine.

Thanks!!

[ankitg7]

Hi @Karan_MSFT : Importing the solution as unmanaged doesn't work. What's the advice for achieving this first in a development environment where we wouldn't want to import managed solution changes? Thx

[carfup]

 @Anonymous &  @ankitg7 
I've just pushed a tool within XrmToolBox to perform those actions in few clicks :

PCF 2 BPF 

https://www.linkedin.com/posts/clemolivier_xrmtoolbox-msdyn365-dataverse-activity-6901472317327638528-5Jay 

Enjoy!

[ankitg7]

@carfup : You are a legend !

[ankitg7]

Just found a problem with the tool, it keeps throwing 'One or more required fields are empty, please fill them.' even when the required fields have been provided value. Looks like all 'param Name' have been internally marked as required.

[carfup]

@ankitg7 Please do not use this post as a "support" page.
Can you please log an issue on the related github project : Issues · carfup/XTBPlugins.PCF2BPF (github.com) and provide as many details as you can so I can try to reproduce / figure out the root cause.
Thank you.