Tutorial: Create workflow extension

This tutorial will show you the process to extend the workflow designer to add custom activities and logic using a workflow assembly, sometimes known as a workflow activity. The extensions you create this way can be used within a workflow, a custom action, or a dialog.

This tutorial uses a very simple example to focus on the requirements and process to:

  • Create a Visual Studio Class Library project
  • Add a CodeActivity class
  • Define input and output parameters
  • Add your business logic
  • Sign and build the assembly
  • Register your assembly
  • Test your assembly
  • Add your assembly to a solution

Prerequisites

  • A Common Data Service instance and administrator privileges
  • Understanding of how to configure workflows. More information: Classic Common Data Service workflows
  • A model-driven app that allows you to edit accounts.

Goal

The example below will create a simple custom workflow activity that may be used in a workflow, dialog, or action process. More information: Configure workflow stages and steps

This custom workflow activity will match the following requirements:

  1. Accept an decimal input parameter
  2. Output a value equal to the input parameter plus 10.

In a workflow for the Account entity it may be used in the following manner to increment the Credit limit value using two steps:

The goal for this tutorial

Step 1 uses the Sample: Increment by 10 custom workflow activity to accept the Account Credit Limit value and increment it by 10. Step 2 uses the Update Record action to update the Account Credit Limit value with the incremented value.

Step 1: Get incremented Account Credit Limit

When the first step is added, the custom workflow activity will be available in a Sample group and have the name Increment by 10.

The increment by 10 step

When configuring the first step by clicking the Set Properties button, the Decimal input property will be required and accept only a decimal value, such as the Credit Limit attribute of the Account entity.

Setting decimal input

Step 2: Set new Account Credit Limit

In the second step, an Update Record action will assign the output of the Get incremented Account Credit Limit step to update the Account Credit limit value with the incremented value.

Update the credit limit

Create a Visual Studio Class Library project

This project will create a simple workflow assembly that will increment an decimal value by 10.

  1. Start Visual Studio.

  2. On the File menu, click New, and then click Project.

  3. Search for Class library and select Class Library (.NET Framework).

    Searching for class library (.NET Framework)

  4. Click Next.

  5. Specify a name and location for the solution.

    Configure your new project dialog in Visual Studio 2019

    Note

    Choose a Project name that makes sense for your project. In this example we will use SampleWorkflowActivity.

  6. Click Create.

  7. In the Solution Explorer, right-click on the project select Properties. On the Application tab, verify that .NET Framework 4.6.2 is set as the target framework.

    set project properties

  8. In the Solution Explorer, right-click the project and select Manage NuGet Packages… .

    manage nuget packages

  9. Browse for the Microsoft.CrmSdk.Workflow NuGet package and install it.

    Install Microsoft.CrmSdk.Workflow Workflow NuGet Package

    Note

    Make sure that the package you are installing is owned by crmsdk. This package will include the Microsoft.Xrm.Workflow.dll include a dependency on the Microsoft.CrmSdk.CoreAssemblies package so that the required Microsoft.Xrm.Sdk.dll assembly is included as well.

  10. You must click I Accept in the License Acceptance dialog.

    Accept license agreement

Rename the class file

  1. In Solution Explorer, right-click the default Class1.cs file and and select Rename.

    Rename Class1.cs file

    Note

    Choose a class name that makes sense for your activity. In this example, we will name the class IncrementByTen.

  2. Select Yes in the dialog box that asks if you would like to rename the class as well.

    Select Yes to rename the class as well

  3. Open the IncrementByTen.cs file, and add the following using directives:

    using System.Activities;
    using Microsoft.Xrm.Sdk;
    using Microsoft.Xrm.Sdk.Workflow;
    
  4. Make the class inherit from the CodeActivity class and give it a public access modifier as shown here:

    public class IncrementByTen: CodeActivity
        {
    
        }
    
  5. Add the Execute method from the CodeActivity class using Visual Studio Quick actions or manually:

    implement codeactivity interface

  6. The class now looks like this:

    public class IncrementByTen : CodeActivity
    {
        protected override void Execute(CodeActivityContext context)
        {
            throw new NotImplementedException();
        }
    }
    

Define input and output parameters

  1. Add a set of input and output parameters where the value of the output parameter will be the value of the input parameter incremented by 10.

    public class IncrementByTen : CodeActivity
    {
        [RequiredArgument]
        [Input("Decimal input")]
        public InArgument<decimal> DecInput { get; set; }
    
        [Output("Decimal output")]
        public OutArgument<decimal> DecOutput { get; set; }
    
        protected override void Execute(CodeActivityContext context)
        {
    
        }
    }
    

    Note

    Notice how .NET Attributes are used to provide metadata about the parameters in the assembly. More information: Add parameters

Add your business logic

Add the logic within the Execute method to apply the logic to increment the input value by 10.

    protected override void Execute(CodeActivityContext context)
    {
      decimal input = DecInput.Get(context);
      DecOutput.Set(context, input + 10);
    }

Sign and build the assembly

  1. Custom workflow activity (and plug-in) assemblies must be signed. In the project properties, under the Signing tab, select Sign the assembly. Below Choose a strong name key file, select the <New...> option. You do not need to set a password for the purpose of this tutorial. For this example we created a new strong name key file named SampleWorkflowActivity.snk

    sign assembly

  2. Build the solution in Debug mode and verify that the SampleWorkflowActivity.dll assembly is in the /bin/Debug folder.

Note

While developing an assembly it is fine to use the Debug build configuration. When you deploy your assembly to a production server or in a solution, you should use the Release build configuration.

Register your assembly

Custom workflow activity assemblies are registered using the Plug-in Registration tool. The tool provides a graphical user interface and supports registering assemblies that contain plug-ins or custom workflow activities. To get the Plug-in Registration tool see: Download tools from NuGet

Connect using the Plug-in Registration tool

  1. After you have downloaded the Plug-in registration tool, click the PluginRegistration.exe to open it.

  2. Click Create new Connection to connect to your instance.

  3. Make sure Office 365 is selected. If you are connecting using a Microsoft account other than one you are currently using, click Show Advanced.

    Logging in with the Plug-in registration tool

  4. Enter your credentials and click Login.

  5. If your Microsoft Account provides access to multiple environments, you will need to choose an environment.

  6. After you are connected, you will see any existing registered plug-ins & custom workflow activities

    View existing plug-ins an custom workflow activities

Register your assembly

  1. Select Register > Register New Assembly

    register assembly command

  2. In the Register New Assembly dialog, click the ellipses button (…) and navigate to the SampleWorkflowActivity.dll in the /bin/Debug folder.

    register assembly dialog

    Note

    Note: With Common Data Service the only valid options for Steps 3 & 4 are selected and invalid options are disabled.

  3. Click Register Selected Plugins. You should see a confirmation dialog.

    registered plug-in dialog

  4. Click OK to close the Register New Assembly dialog.

Configure activity names

  1. In the list of Registered Plugins and Custom Workflow Activities locate the (Assembly) SampleWorkflowActivity and expand it to show the (Workflow Activity) SampleWorkflow.Activity.IncrementByTen - Isolatable.

  2. Select the (Workflow Activity) SampleWorkflow.Activity.IncrementByTen - Isolatable and in the Properties area edit the Editable properties using the values in the following table:

    Editable Field Original Value New Value Description
    Description Returns the value of the input parameter plus 10. Not visible in the UI of the process designer, but may be useful when generating documentation from data drawn from the PluginType Entity that stores this information.
    FriendlyName a GUID value IncrementByTen User friendly name for the plug-in.
    Name SampleWorkflowActivity.IncrementByTen Increment By 10 The name of the menu represented
    WorkflowActivityGroupName SampleWorkflowActivity (1.0.0.0) Sample The name of the submenu added to the main menu in the Common Data Service process designer.

    Note

    If the Name and WorkflowActivityGroupName are set to null, the custom activity will not be visible in the process designer.

  3. Click the Save (icon) to save the changes.

    Save workflow activity properties

Test your assembly

You can test your new workflow activity by creating a process that will use it. Use these steps to create the Workflow process described in the Goal section above:

  1. Open PowerApps

  2. Select Solutions.

  3. Open the CDS Default Publisher solution.

  4. In the menu, expand the ... and choose Switch to classic.

    Switch to classic user interface

  5. Select Processes in the Components list

  6. Select New and in the Create Process dialog enter the following:

    Field Value
    Process name Test of SampleWorkflowActivity.IncrementByTen
    Category Workflow
    Entity Account
    Run this workflow in the background (recommended) deselected

    Note

    The option to Run this workflow in the background has been de-selected to make this a real-time (synchronous) workflow. This will make testing simpler.

    Creating a process

  7. Click OK

  8. Apply the following changes:

    Field Value
    Scope Organization
    Start when: Record fields change selected, and name field specified in the dialog.

    configuration of a test workflow

    Note

    Setting Scope to Organization creates a workflow that can be applied by anyone in the organization.

  9. Add the following Step:

    Add the SampleWorkflowActivity.IncrementByTen step

  10. Set the Step Description to Get incremented Account Credit Limit and click Set properties.

  11. Set the value of the Decimal input property to the Credit Limit of the account with a default value of 0.

    Set the decimal input property

  12. Click Save and Close.

  13. Add an Update Record step:

    Add an update record step

  14. Click Set Properties and set the value of the Credit Limit to the value of the Get incremented Account Credit Limit step.

    Set the value of the credit limit

    The workflow steps should look like this:

    The completed workflow

  15. Click Save and Close.

  16. Activate the workflow by clicking Activate in the menu...

    activate workflow command

  17. And click Activate in the Process Activate Confirmation dialog.

    Process Activate Confirmation dialog

  18. Navigate to a model-driven app and view a list of acccounts.

  19. Select an account.

  20. Edit the Account Name field value.

  21. Save the account record.

  22. Verify that the account you edited has Credit Limit value has increased by 10.

    verify account credit limit incremented

Add your assembly to a solution

To distribute a custom workflow activity in a solution, you must add the registered assembly that contains it to an unmanaged solution.

  1. Open the unmanaged solution you want to add the assembly to using PowerApps

  2. Select Add existing > Other > Plugin assembly

    Add existing plugin assembly

  3. Search for the Plugin assembly by name, in this case 'SampleWorkflowActivity'.

  4. Select the plugin assembly and select Add.

See also

Workflow extensions
Sample: Create a custom workflow activity
Sample: Update next birthday using a custom workflow activity
Sample: Calculate a credit score with a custom workflow activity