SDK Extension Libraries

This article describes how to create a project (library) with included plugins, what references to add and how to turn it into a WSP package and install it on SharePoint. It also describes how to register such a plugin on the list of ‘SDK plugins’ in Designer Studio, and how to ensure that it was registered correctly.

Creating a project

To create a project including plugins, it is best to use a ready project template, which is available in the Resources section.
Then in Visual Studio select File->New->Project. As the project type, select SharePoint 2013 – BPS Extensions.
BPS Extensions template
After providing a name for the project and clicking OK, a new window will appear asking for a site that will be used for testing and debugging the solution. It’s also important to set the correct trust level for the solution – Deploy as farm solution.
Solution security level
Clicking finish will conclude the creation process – a project for SDK plugins is ready.

References within a project

If you are using a version of BPS older than 8.3, then it is necessary to change the reference to the MyGeneration.dOOdads library. From version 8.3 onwards, BPS uses MyGeneration.dOOdads version 6.0.0.0. Earlier versions of BPS still use version 5.0.0.0.
If you would like to use version 5.0.0.0, remove the reference to MyGeneration.dOOdads and add it again this time selecting the correct file. If BPS is installed on the server, then the correct version of this library can be found in the folder:
“C:\Windows\assembly\GAC_MSIL\MyGeneration.dOOdads\5.0.0.0__c30f1f18c194ceba\MyGeneration.dOOdads.dll”.

The remaining references in the project that are connected to WEBCON BPS are as follows: WebCon.WorkFlow.Data, WebCon.WorkFlow.SDK.Logic and WebCon.WorkFlow.Object.
In the WebCon.WorkFlow.Data library, there are Data Access Layer classes which provide access to data from the BPS database. They are rarely used in add-ins, but they may come in handy when there is a need to obtain unusual data from the BPS database. Please note however, that the BPS database cannot be modified in any way using these objects, that is done using the provided SDK object model instead.
The WebCon.WorkFlow.Object library contains base classes for all types of SDK plugins, e.g. WFCustomAction, from which all custom actions must inherit.
The WebCon.WorkFlow.Logic contains tool classes, as well as classes used to operate on elements of the BPS system.

A list of all classes available in these libraries can be found in the Resources section in the online reference manuals.

Changing the site URL

If there is a need to test or debug solutions on a different page than the one given during project creation, the site address can be changed in the same way as any other standard SharePoint Solution project. This option is available in the menu under View -> Properties Window, with the address located in the Site URL field.

Using your own key for signing

The project, that was created using templates, is always signed with an automatically generated key. All libraries deployed in SharePoint must be signed. If you want to use your own key for signing, it can be included in the project and the signing options can be modified in the project settings.

Add your ‘key’ file to the project folder, like so:
Project folder
Next, the file should be included in the project in Visual Studio. In order for the file to be visible, select the project in Solution Explorer and turn on ‘Show All Files’. Find the newly added ‘key’ file, right-click it and select ‘Include in Project’.
Show all files
To sign a project with this key, go to the project properties (right-click on the name of the project and select Properties). Once inside the project properties, in the ‘Signing’ tab, choose the file with key which you want to use.
Project signing

Creating a new SDK action

When a project is created from a template, a sample of every type of SDK plugin is also generated. The CustomAction folder contains an example of an SDK action named Sample. To add a new SDK action, first select the folder where the class will be located, right-click and choose Add -> New Item. On the list of templates find and select ‘BPS Custom Action’.
Add BPS Custom Action
Based on this template, a class will be created which will inherit from the appropriate base class as well as having overloaded elements, which should be implemented in every SDK action. These elements are: two Properties – PluginName, PluginDescription, and a method – Run(RunCustomActionParams args).
The PluginName property returns the action name. The name returned here will be visible in Designer Studio during plugin registration.

Property PluginDescription contains the action description. It will also be visible in Designer Studio.

It’s a good idea to return the correct action names and descriptions in these properties, so that it is easier to find them later during registration (especially if there are many actions in the project), and also to use these same names in Designer Studio for process configuration.

Run(RunCustomActionParams args) is a method activated by BPS when an action is executed.

The action’s logic should be contained within it:

If we want to create an SDK action without using a template, it is important to ensure that it is public class and inherits from WFCustomAction. It is necessary to designate an appropriate namespace within the class:

as well as to override the properties: PluginName, PluginDescription, and method: Run(RunCustomActionParams args).

Creating a WSP package

A WSP package is an installation file for SharePoint Solution projects. It is by far the best way of deploying projects on the production environment. In order to create a WSP package, simply deploy the solution on the site associated with the project. This is done by right-clicking the project and clicking Deploy.
Deploy wsp package
Visual Studio will install the Solution on the associated site. This should be enough to conduct tests on the development environment. The file containing the WSP package will be saved in the project folder – this file may then be used to install the solution on the production environment.

Installing a WSP package using PowerShell

The WSP package may be installed using PowerShell.
Run Windows PowerShell as an Administrator. First we must add Microsoft.SharePoint.PowerShell ,
to do so, type in:

Next, add the Solution to SharePoint, this can be done with the command: Add-SPSolution.
As the parameter, provide the full path to the WSP file:

After adding the solution to SharePoint it needs to be deployed using the command: Install-SPSolution.
As the identity, provide the name of the WSP file. Optionally, define in which SharePoint web application the solution will be installed.

Registering a Plugin in Designer Studio

Once the Solution is installed on SharePoint, the plugin can be registered in BPS Designer Studio. Go to the Plugins tab, and select the appropriate type of plugin. In this example, it will be a Custom action (SDK).
Select the desired type and click New on the toolbar.
Register custom action plugin
A new entry will be created representing a plugin, this blank form can be filled out manually, but is much more convenient to just select the plugin from amongst those installed on SharePoint. Click the Choose button, this will open a window for plugin selection:
Choose dll with plugins
Find the library file (.dll) containing the plugin. You may enter the partial name of the dll file – as it will speed up the search (e.g. BPSExtensionsProject).
Select the appropriate dll file from the list.
Once selected, all plugins of the previously selected type (in our case it is Custom action (SDK)) will be loaded. The correct plugin can be found by its name and description, which were entered earlier into its class properties.
Choose plugin
After selecting the plugin, click OK. The entry will be completed with data from the plugin class. The entry can be modified according to your needs. Just keep in mind, that when configuring a process in Designer Studio, this Custom action will be available under the name entered into this field:
Select plugin
It is also possible to check whether this action was registered correctly, and if it can be successfully launched in SharePoint, by pressing the Test button.

Pressing the button should give the following message:
Plugin test message
Remember to save the plugin configuration. Only saved plugins will be visible in other parts of the system. Any number of actions can be added in this way.

Adding more actions to a project with existing plugins

Adding multiple extra actions (or other plugins) to the same project will not remove or deactivate previously registered plugins.

If we create new actions in the same project and install it (via WSP package) on SharePoint, the plugin library will be overwritten with the updated version. This will make it possible to register new actions, while all existing actions will remain unchanged.

The only situation when existing actions may cease to work correctly, is when you introduce a breaking change in their configuration. Such actions will need to be reconfigured. However, if we improve/expand an existing action without modifying its configuration, installing this project in SharePoint is all that is necessary. The action will still be correctly registered, and every instance of it being used in BPS Process configuration will remain intact. The way the action works will be updated according to the new version of the library file.

Launching an SDK action

In order to launch an SDK action (e.g. when exiting a step), we must add it to the workflow configuration. In Designer Studio, select the desired workflow and then the step on which you wish to add the action (Select one of the workflow steps and press the Edit button). Now go to the Actions tab and select one of the events on the list, which define when the action will be triggered (e.g. On exit).
Add new action
Press the Add button to add a blank action template. As the Action kind select – Run an SDK action. Now every action registered in the system will be available in the Plugin (SDK) dropdown menu. Find the action you wish to use and select it.
Select plugin
Whenever the BPS system executes this action, it will activate the registered plugin. Additionally every SDK action added to the process can be individually configured in every place that it is used. Configuring SDK actions in Designer Studio has been described in the following article: SDK action configuration.