(loading)(Sign In to view your notes)(no notes defined)(no community comments defined)Are you sure you want to delete this item? This action cannot be undone.
K2 blackpearl


How to create a Custom Inline Function
Developer Reference > Extending the K2 Platform > How to create a Custom Inline Function Send feedback

Glossary Item Box

How to Create a Custom Inline Function

Inline functions allow simple text manipulation, data type conversions, and math and date calculations in the context of a process. These functions run within the K2 Workflow Server, so it is recommended that any custom functions be somewhat simple and perform their operations efficiently.

With this in mind, you can create custom functions in lieu of writing custom code. This also allows process designers to call business logic through a declarative, UI-based manner instead of resorting to custom code in server events.

 

Inline Functions run in the context of the K2 Workflow Server, so they have the potential to affect server performance. Highly complex Inline Functions should therefore be avoided.


 

Designing the Custom Inline Function Assembly

The first thing you need to do is to create a Windows Class Library. The following references are necessary to add to your project:

You will need using statements for the following namespaces:

 

You will need to configure the following Project Properties:


You should add a resource file to the project to manage your strings.

Do not change the namespace of the Microsoft Visual Studio solution for the Inline Function. Locating all the associated namespace properties is difficult and if one is missed out and not changed to match the new name the Inline Function will not show in the K2 designer. Visual Studio will also not report an error.

Once you have the project set up, you can start adding your classes and methods. Each class may represent a series of functions, with each method corresponding to individual functions displayed in the K2 Context Browser.

You can add functions to the built-in categories or create your own categories of functions, but any single class can only contain functions of a single category because this is determined at the class level

The built-in categories are as follows:

 

Defining the Category

At the class level, the Category Attribute is used to determine which category the functions will appear in. For example, to create a custom category your code attribution would look like the following:

[Category("MyInlineFunction.Resources", "MathCategory", typeof(MyMath))]

The namespace of this custom function project is "MyInlineFunction" and a resource string has been defined, "MathCategory," which contains the name of the category. "MyMath" is the name of the class that is attributed with this category.

RC Note: Adding a custom function to a built-in category may result in an exception when you click on the function tab in the K2 Context Browser. A built-in category attribution looks like the following:

[Category("SourceCode.Workflow.Functions.Resources", "CategoryConversion", typeof(Conversion))]

Defining the Name, Description, and Icon

At the method level, attribution defines the name, description and icon associated with the each function. For example, to define your custom function your code attribution would look like the following:

[DisplayName("MyInlineFunction.Resources", "MyMathFunctionName", typeof(MyMath)), Description("MyInlineFunction.Resources", "MyMathFunctionDescription", typeof(MyMath)), K2Icon(typeof(MyMath), " Resources.MyIcon.png")]

The resource strings "MyMathFunctionName" and "MyMathFunctionDescription" are defined in the project. The .png image is also added to the project Resources folder. A .png file should be used instead of an icon (.ico) file, and should be 16 x 16 pixels. Ensure that the Build Action for the image file is set to Embedded Resource when the project is built, otherwise it will not render in the K2 designers.

The K2 Designer for SharePoint cannot use the Embedded Resource to render the image. The image files must be copied to the following location: C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\LAYOUTS\WebDesigner\Images\Functions for MOSS or WSS. For SharePoint 2010 copy the image files to: C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS\WebDesigner\Images\Functions.

When an image is added to a project as an Embedded Resource it will be stored in the Resources subfolder of your project and need to be accessed as “{ResourcesFolder}.{FileName}” via the attribute.  The icon file names in the SharePoint images directory must match the full name of the attribute.  In this example, the file on the SharePoint server should be named “Resources.MyIcon.png”.

Defining the Parameters

The parameters of your method must also include a name and a description. The data type of these parameters appears after the name of the function, so do not include any characters that may confuse the process designer, especially parentheses.

All methods must be declared Public methods or they will not appear in the K2 Context Browser.

For example, the following method adds two numbers and the parameters are of type long.

public static long MySum(

[DisplayName("MyInlineFunction.Resources", "MyMathFunctionParm1Name", typeof(MyMath)),

Description("MyInlineFunction.Resources", "MyMathFunctionParm1Description",typeof(MyMath))]

long value1,

[DisplayName("MyInlineFunction.Resources", "MyMathFunctionParm2Name", typeof(MyMath)),

Description("MyInlineFunction.Resources", "MyMathFunctionParm2Description", typeof(MyMath))]

long value2)

     {

         return value1 + value2;

     }

 

Deploying the Custom Inline Function

  1. Close any designers that may currently have the function assembly loaded.
  2. Shut down the K2 Server.
  3. Build your custom inline function project

Deploy the resulting assembly to the following locations:

  1. For K2 Studio
    • Copy to <install drive>:\Program Files\K2 blackpearl\Bin\Functions
  2. For K2 Designer for SharePoint
    • Copy to <install drive>:\Program Files\K2 blackpearl\Bin\Functions on all the SharePoint web front-ends
    • GAC the assembly on all SharePoint web front-ends running the K2 for SharePoint components
    • It is necessary to deploy the function assembly in the GAC or K2 Designer for SharePoint will not operate at all and will result in an error.
  3. For K2 Server
    • Copy to <install drive>:\Program Files\K2 blackpearl\Host Server\Bin
The first and second locations allow K2 designers to see the function, while the third location allows the Host Server to use the function. If deploying only to a server, you can limit the deployment of the assembly to the third location.

In summary the following is required:

For runtime, the Inline Function assembly must be copied to [K2 blackpearl]\Host Server\bin folder of the K2 Server machine
For design time, the Inline Function assembly must be copied to both the [K2 blackpearl]\Host Server\bin and [K2 blackpearl]\Bin\Functions folders of the Development machine

 

  1. Start the K2 blackpearl Server
  2. Open a Windows-based K2 designer (K2 Studio, K2 for Visual Studio or K2 for Visio) and test your function

    NOTE: These are the icons you see if you did not embed your icon resource file correctly.
  3. Open K2 Designer for SharePoint to test that location as well

An example project of how to create a custom inline function has been included: SourceCode.Samples.Functions File

Add a new Private Note
Add a new Community Comment
©2011. All Rights Reserved.