Create your first plugin

Creating a project with WEBCON BPS SDK plugin

This article will show you step-by-step how to create a project that contains a custom action – which is one of the types of SDK plugins.

In order to develop your own plugins you may need the SDK license and you have to have WEBCON BPS SDK installed. As an example, we will create a project with a simple custom action which will update the value in a form field.

Setup

At the moment, we provide two different project templates.

• The BPS 2021 Extensions – Logic is the template created in order to help you develop logic parts of your plugins.
• The BPS 2021 Extensions – SharePoint 2013|2016|2019 UI Controls is the template created in order to help you develop the UI parts of your plugins.

You can find the BPS 2021 Extensions – SharePoint 2013 UI Controls, BPS 2019 Extensions – SharePoint 2016 UI Controls and BPS 2019 Extensions – SharePoint 2019 UI Controls templates installers in resources inside “Visual Studio templates” section.

When it comes to WEBCON BPS 2021 Extensions – Logic templates installer you can find it in Visual Studio Marketplace You can also download it through “Extensions and Updates…” Visual Studio extensions manager.

Creating project

The process of creating the BPS Extensions project is very simple. You can create Class Library project but you can also make use of one of our templates which makes this process even more effortless.

Make sure that checkbox “Place solution and project in the same directory” is not checked, because it may result in the incorrect process of creating and publishing package with your plugins.

Adding WEBCON BPS SDK libraries files

If you are using one of our project templates you can skip this step, because their goal is to set everything up for you. However we recommend reading this short section so that you can have the knowledge of how you can add WEBCON BPS SDK DLL files to projects created without our templates so that you will be able to write your plugins.

The easiest way to use libraries is to use the NuGet packages. You can download them through built in Visual Studio NuGet Package Manager.

You can also make use of other options provided by NuGet which are listed here Just grab the version for which you will be developing your plugins, add it to your project references, and you can start writing your code.

Creating WEBCON BPS SDK plugins

To develop an SDK plugin, you can also make use of one of the provided templates to speed things up. They will guide you step-by-step through the configuration process.

The BPS 2021 Custom Action template contains an example of code which we will use in this article. Just uncomment the code shown here:

using WebCon.WorkFlow.SDK.Common;
using WebCon.WorkFlow.SDK.ConfigAttributes;
namespace CustomActionExample
{
    public class ChangeFormFieldValueConfig : PluginConfiguration
    {
        //[ConfigEditableText(DisplayName = "Source form field ID")]
        //public string SourceFormFieldID { get; set; }
        //[ConfigEditableText(DisplayName = "Destination form field ID")]
        //public string DestinationFormFieldID { get; set; }
        [ConfigEditableText(DisplayName = "Price form field ID", Description = "ID of the form field which contains price of the product")]
        public string PriceFormFieldID { get; set; }
        [ConfigEditableInteger(DisplayName = "Price")]
        public int Price { get; set; }
    }
}

using WebCon.WorkFlow.SDK.ActionPlugins;
using WebCon.WorkFlow.SDK.ActionPlugins.Model;
namespace CustomActionExample
{
    public class ChangeFormFieldValue : CustomAction
    {
        public override void Run(RunCustomActionParams args)
        {
            //Copy value from source form field to destination form field
            //string sourceFormFieldValue = args.Context.CurrentDocument.GetFieldValue(Configuration.SourceFormFieldID).ToString();
            //args.Context.CurrentDocument.SetFieldValue(Configuration.DestinationFormFieldID, sourceFormFieldValue);
            //Save value to form field
            args.Context.CurrentDocument.SetFieldValue(Configuration.PriceFormFieldID, Configuration.Price);
        }
    }
}

If you would like to go through the creation process without using our templates, we recommend reading next two sections. Otherwise you can skip them and go straight to section named “Plugins package manifest”.

Creating a plugin configuration without templates

In order to create a plugin configuration, you have to derive from PluginConfiguration class available in WebCon.WorkFlow.SDK library. The plugin configuration class consist of set of public properties. Every property has one of our attributes which are all in the form of Config[…] The description of each of them is available in a separate article.

using WebCon.WorkFlow.SDK.Common;
using WebCon.WorkFlow.SDK.ConfigAttributes;
namespace CustomActionExample
{
    public class ChangeFormFieldValueConfig : PluginConfiguration
    {
        //put your code here
    }
}

Creating a custom action without templates

In order to create custom action you have to derive from CustomAction generic abstract class, and then pass as the type the parameter plugin configuration which you have created in the previous step. CustomAction generic abstract class contains set of virtual methods and properties that you can override in order to provide your custom implementations. One of them is the Run method which we are going to use and which is invoked in many different scenarios. Again, you can read more about all of these methods and properties in a separate. We will not quote it here to make this example as simple as possible.

using WebCon.WorkFlow.SDK.ActionPlugins;
using WebCon.WorkFlow.SDK.ActionPlugins.Model;
namespace CustomActionExample
{
    public class ChangeFormFieldValue : CustomAction
    {
        public override void Run(RunCustomActionParams args)
        {
            //put your code here
        }
    }
}

Plugins package manifest

The Manifest is the JSON file specifying information about plugins contained within the DLL file. This metadata is then used by plugin registration mechanism to discover the proper code. If you use default settings applied by our project template, the manifest will be filled in automatically every time you add a new plugin. You can check the current state of your manifest and edit it inside the JSON file which name is the same as the project.

[
  {
    "Guid": "0f6a296b-3359-40b3-be3f-cd61de12b120",
    "Name": "ChangeFormFieldValue",
    "Description": "Custom action that updates form field value",
    "Assembly": "CustomActionExample",
    "Class": "CustomActionExample.ChangeFormFieldValue",
    "Type": "CustomAction"
  }
]

Creating Strong Name Key

For development purposes, we sign all projects created with the use of our templates with temporary key (temporary_key.snk). Although it may be enough to test our plugins we recommend to sign projects with your own digital signing key.

Creating a plugin package

In order to register plugins in WEBCON BPS – Designer Studio, you have to create package which is a zipped directory that contains the project’s DLL file and the manifest. The BPS 2021 Extensions contains the WEBCON BPS SDK Tools that will help you in publishing your plugin package; additionally, they will help in developing Form Field Extension JS, which is described in this article. This process consists of increasing the assembly version, building the startup project, and at the end creating the plugin package which contains all the plugins found in the selected project. The package is published to the “Publish” directory inside your project.

Registering plugins package

You register plugins package in WEBCON Studio as shown below. It will register all your plugins inside the package automatically.

Plugins packages are versioned. Without going into excessive details, we use the AssemblyVersion attribute to control it. All you have to do is to keep in mind that any changes to plugins must be followed by increasing assembly version number. This is done by the tool when you use the publish feature, but you can also increase this number manually if you choose to do everything yourself.

using System.Reflection;
using System.Runtime.InteropServices;
/// General Information about an assembly is controlled through the following 
/// set of attributes. Change these attribute values to modify the information
/// associated with an assembly.
[assembly: AssemblyTitle("CustomActionExample")]
[assembly: AssemblyDescription("WEBCON BPS Extensions")]
[assembly: AssemblyProduct("CustomActionExample")]
/// Setting ComVisible to false makes the types in this assembly not visible 
/// to COM components.  If you need to access a type in this assembly from 
/// COM, set the ComVisible attribute to true on that type.
[assembly: ComVisible(false)]
/// The following GUID is for the ID of the typelib if this project is exposed to COM
[assembly: Guid("e02c9c6a-611c-4a4c-87f1-369c50544223")]
/// Version information for an assembly consists of the following four values:
///
///      Major Version
///      Minor Version 
///      Build Number
///      Revision
///
/// You can specify all the values or you can default the Build and Revision Numbers 
/// by using the '*' as shown below:
/// [assembly: AssemblyVersion("1.0.*")]
[assembly: AssemblyVersion("1.0.0.1")]
[assembly: AssemblyFileVersion("1.0.0.0")]
[assembly: AssemblyInformationalVersion("1.0.0.0")]

Configuring the action

The last step is configuring the custom action that you have written. For the purpose of this example we will create new WEBCON application called HelloWorldApplication with HelloWorldProcess which will contain just two steps – Start and Finish (positive). We will attach created action on exit path from Start step.

Start with creating the structure like below:

Next, create a form field inside your process which will be updated using our custom action.

In order to make this form field visible on your forms, you have to check the appropriate checkbox in field matrix tab inside your Main form configuration.

Then to add the custom action to be triggered On exit from the Start step. Add new action, set its type to ‘Run an SDK action’ and select it from ‘Plugin (SDK)’ dropdown. Once you have done this you can click ‘Configure’ button to fill configuration of your custom action.

Make sure to save your process to confirm all your changes.

And that’s it. You have created your very first custom action which will modify the value of the defined form field. Congratulations!