Plugins configuration

This article contains basic information on how to configure an SDK action. It describes how to create configuration fields inside the code of an SDK add-on, and how these configuration fields will be visible as widgets and prompts in Designer Studio. Additionally, it touches on the subject of reference tags and how they can be used to configure this action.

Action example

Action description

Adding configuration properties will be shown on a sample action – used for registering vacation dates in an external system. The action shown here will be greatly simplified, and should be attached to a vacation process. After a vacation is approved in the BPS system, this action will use a Web Service to register this vacation in an external HR system. The action should be executed when a vacation request is approved.

To do this, VacationWebService is invoked, the address is located in the WebServiceUrl parameter. The action invokes the web service method: RegisterVacation while using the following parameters: Login (the user for who would like to take a vacation), StarDate (start of the vacation) and EndDate (end of the vacation).

In the most basic scenario imaginable, these parameters have set values located in the code. This means that the action will only be executed for one specific configuration set in the code. The idea however, is for the login and dates to be loaded dynamically from a workflow element in the BPS system (the vacation request), instead of being set to rigid values.

public override Task RunAsync(RunCustomActionParams args)
{
    try
    {
        string Login = "WEBCON\\t.green";
        DateTime StartDate = new DateTime(2016, 2, 27);
        DateTime EndDate = new DateTime(2016, 3, 10);
        string WebServiceUrl = "http://localhost:55636/Vacation.svc";
        var client = new VacationWebService(WebServiceUrl);
        client.RegisterVacation(Login, StartDate, EndDate);
    }
    catch (Exception ex)
    {
        args.HasErrors = true;
        args.Message = "Error: " + ex.Message;
        args.LogMessage = ex.ToString();
    }
    return Task.CompletedTask;
}

Action configuration in Designer Studio

Every registered SDK action in the process can be configured. Go to wherever the action is defined and click Configure.

If the action does not make any configuration elements available, the configuration window will be empty.

Adding an action configuration

Basics

If we want the parameters to be configurable in the action configuration window, we need to create a public property in the class and decorate it with the desired attribute. In order for the property to work correctly it must also have a public get and set methods.

[ConfigEditableText(DisplayName = "Login", Description = "Login of the person")]
public string Login { get; set; }

WEBCON BPS SDK provides several attribute classes, which can be assigned to a configuration property. They are available in namespace WebCon.WorkFlow.SDK.Objects.ConfigAttributes. Each of these attributes will cause a parameter to show up in the configuration window in a unique way – e.g. the widgets will be different.

Certain attributes can only be used on specific types of properties, there are some however, that can be used on multiple types. In this example, we used the most common configuration attribute: ConfigEditableText. It displays the parameter in the configuration window in the form of an editable text prompt. Data entered into this text prompt will be set to the property of a class instance.

Here is what the ConfigEditableText attribute looks like once we enter the SDK action configuration window in Designer Studio. A new element will appear in the window named Login. This name is defined by DisplayName and the description is defined by the Description property.

Converting to other types

The ConfigEditableText attribute is most commonly associated with the property type: string. The value entered into the text prompt is then converted in to the set property type – so in this case, string. It is however possible to use ConfigEditableText for other property types too. For example: DateTime, the value entered into the text prompt will be converted to DateTime type. If the data entered into the text prompt of the action configuration is incapable of being converted into the desired type, an appropriate error message will be displayed when attempting to execute the action. Here are examples of using the ConfigEditableText attribute for properties that store dates:

[ConfigEditableText(DisplayName = "Start date", Description = "Vacation start date")]
public DateTime StartDate { get; set; }
[ConfigEditableText(DisplayName = "End date", Description = "Vacation end date")]
public DateTime EndDate { get; set; }

In the example posed above, the action configuration will return an error, because the ‘End date’ cannot be converted into DateTime. In order for it work, the End Date would have to entered like the Start date, which has the correct format.

Using reference tags

We can configure the action to enter specific values into the prompt fields, however the end goal is to have the action dynamically obtain values from the workflow element for which it is invoked (i.e. an approved vacation request). While the Web Service address could obviously be entered directly into the configuration, dynamic values like the login and dates should come from the workflow element. It is very easy to define such a configuration using reference tags. Tags are represented by rectangles with text inside them, or as ID’s enclosed by curly brackets. (e.g. a Form field tag in advanced mode may look like: 259).

The tree on the right-hand side of the action configuration window contains all possible reference tags that can be used in the current context. You can either set the focus on the desired prompt and double-click the tags on the tree, or drag-and-drop them from the tree into the prompts.

Before the action is launched, all of its configuration parameters are evaluated. First of all, reference tags are supplanted by the corresponding value from the processed workflow element (or other contextual values), and then they are converted to the defined property type. The final value is entered into the action property and the action is then executed with the Run method.

It is possible to not replace reference tags with contextual values, by setting the property SkipTagsEvalution to true in the ConfigEditableText attribute.

Final effect