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 Activity 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


  • You must have Windows Workflow Foundation included as an individual component with Visual Studio 2017. More information: Visual Studio requirements
  • 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.


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 Activity 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. In the New Project dialog box, under Other Languages, expand Visual C# and select Workflow, and then select Activity Library.

  4. Specify a name and location for the solution, and then click OK.


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

    create workflow activity project

  5. Navigate to the Project menu and select Properties. On the Application tab, specify .NET Framework 4.6.2 as the target framework.

    set project properties

  6. Delete the Activity1.xaml file in the project.

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

    manage nuget packages

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


    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.

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

    Accept license agreement

Add a CodeActivity class

  1. Add a class file (.cs) to the project. In Solution Explorer, right-click the project, select Add, and then click Class. In the Add New Itemdialog box, type a name for the class, and then click Add.


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

    Add a class

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

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

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

    implement codeactivity interface

  5. 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
        [Input("Decimal input")]
        public InArgument<decimal> DecInput { get; set; }
        [Output("Decimal output")]
        public OutArgument<decimal> DecOutput { get; set; }
        protected override void Execute(CodeActivityContext context)


    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. Sign the assembly. In the project properties, under the Signing tab, select Sign the assembly and provide a key file name. Custom workflow activity (and plug-in) assemblies must be signed. 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.

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: 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 ( Sample The name of the submenu added to the main menu in the Common Data Service process designer.


    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


    These values will not be visible in the unmanaged solution when you test your workflow activity. However, when you export a managed solution that includes this workflow activity these values will be visible in the process designer.

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. Switch the design mode from Canvas to Model-Driven.

  3. Select Solutions.

  4. Open the Common Data Service Default Solution.

  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


    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


    Setting Scope to Organization creates an on-demand workflow that can be applied by anyone in the organization.

  9. Add the following Step:

    Add the SampleWorkflowActivity.IncrementByTen step


    As mentioned earlier, the custom values you set in Register your assembly will not be applied in the designer until after the workflow activity is imported as part of a managed solution.

  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 Solution Explorer.

  2. Select Plug-in Assemblies in the list of components.

  3. Click Add Existing in the command bar.

    select add existing

  4. In the Select solution components dialog, select the SampleWorkflowActivity you created and click OK.

    Add SampleWorkflowActivity

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