cancel
Showing results for 
Search instead for 
Did you mean: 

Preview Custom Controls in Business Process Flows

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. 

Custom controls in a BPF.jpg

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.

Activate or update a BPF to generate the FormXML.jpgActivating/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 solution.jpgCreating 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 solution.jpgSaving 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 solution.jpgAdding 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

    Selecting BPFs to add to the solution.jpg

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

    Exporting a solution.jpgExporting 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’

    Export wizard 1 of 3.jpg

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

    Export wizard 2 of 3.jpg

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

    Export wizard 3 of 3.jpg

  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 solution.jpgDeleting 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.

Accessing the lead form customization file.jpg

  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 valueIdentifying the uniqueid for controls.jpgLocating 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 definition.jpgCustom 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

Accessing the customization file.jpg

To add custom controls in this document:

  1. Locate the FormXML for the ‘Lead to Opportunity Sales Process’ entityLocating the BPF FormXML.jpgLocating 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 tabIdentify BPF stages.jpgIdentifying 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.jpgIdentifying 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.Adding the unique id.jpgPasting 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.jpgImporting 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 customizations.jpgPublishing 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!!

Meet Our Blog Authors
  • Working daily with Microsoft Cloud to deliver the needs of my company, my customers and various Microsoft communities and forums. | Office 365 | Flow | PowerShell | PowerApps | SharePoint |
  • Co-founder of https://plumsail.com, Office 365 and SharePoint expert. Passionate about design and development of easy to use, convenient and flexible products.
  • Microsoft Business Apps MVP. Owner of ThriveFast, an Office 365 consulting company.
  • 7x Microsoft Business Solutions MVP (CRM)
  • Solution Architect with Slalom, and organizer of the Boston Office 365 User Group, and long term SharePoint/Office 365 veteren. Find more at http://www.davidlozzi.com. Follow @DavidLozzi
  • I'm keen in MS technologies, SharePoint, Office 365 and development for them
  • Daniel is a Business Productivity Consultant & Microsoft Business Solutions MVP who is very enthusiastic about all things Office 365, Microsoft Flow, PowerApps, Azure & SharePoint (Online). Since the preview, Daniel has been working with Microsoft Flow and later on with Microsoft PowerApps. That led to him being awarded an MVP Award for Business Solutions. He loves to blog, present and evangelize about improving productivity in the modern workspace with these amazing tools!
  • Michelle is an Office 365 solution architect in Twin Cities, MN. She has been delivering business collaboration solutions for years with her focus on SharePoint and Office 365. Michelle is a recent board member of the Minnesota Office 365 User Group and has been a member of the SharePoint community since 2009. She is a frequent speaker at MNSPUG and SharePoint Saturday and co-chaired the Legal SharePoint User Group for 4 years. Her most frequent projects have involved rolling out a large deployment of Office 365, SharePoint Online intranet, build of a "CHAMPS" Office 365 user adoption program and most recently, SharePoint On-Premise to Online Migration. Michelle is very excited about cloud technology as it is shifting her IT Pro focus to collaboration strategy and technical adoption.
  • I'm a Microsoft Office Servers and Services MVP with a special interest in SharePoint, Office 365, Microsoft Flow, Microsoft Teams and PowerApps. I work at Triad Group Plc ( https://triad.co.uk)