Parts of a custom action solution

This topic provides an overview of the elements needed to add a custom action to Nintex Workflow.

A custom action requires as input context information from the workflow. For example you may enter parameters in the action configuration page. Your action code will then read the context, and pass the parameters to your method contained in the action. The method will perform its function and then return the output which will then be placed back into the workflow context where it can be consumed by other actions in the workflow.

A custom action is composed of both the action in the Workflow designer which includes the action and the action configuration page, but is also composed of the code and assets in the SharePoint solution. First we will look at the example in the context of the Workflow designer, and then we will look at the Visual Studio solution and assets that make up the SharePoint solution.

The BasicAction example takes a single word and returns the first definition in the Merriam-Webster Dictionary. The action uses the HttpWebRequest class from the .NET Net library to make a REST call using the GET method to the Merriam-Webster API. The API takes a base URL, a word, and then an API key and return an XML object that contains information about the world. In this case we are looking to grab the first definition, and do so with an XPath Query. You can refer to the WebCallAction class in the BasicAction solution to review the code.

For more information about the Merriam-Webster Dictionary API, see http://dictionaryapi.com. You will need to request your own key to make the sample work.you

Basic Action Example in the Workflow designer

The following workflow shows the BasicAction added to a simple Nintex workflow. The workflow has two variables defined: word and definition. The first workflow action, Set variable, loads a word set in the SharePoint list. And then the BasicAction looks the word up in the Merriam-Webster Dictionary API, and adds the definition to the definition variable. And then the third action inserts the definition text into the definition column in the SharePoint list. In building the workflow, drag the BasicAction from the Custom Action group in the toolbar. And then enable the workflow to start from a list item.

Figure - Example Workflow using the Basic Action

When setting up the workflow in the designer, open the configuration page and added the variables defined in the workflow. Add the API key requested from Merriam-Webster.

You can find step-by-step instruction on setting up the workflow after installing the BasicAction solution, Create a workflow to test the action.

Figure - Basic Action Configuration Page

Note the data type of these parameters. Word is a single line string. Store Definition in is a Nintex Workflow variable, and is selected in the configuration page by a list. And the API Key is also a single line string.

Caution: In defining the API Key you will want to use your own key obtained from Merriam Webster. You will want to format the key with the "?key=", i.e., ?key=<yourkey>

In the SharePoint list, type a word in the word column, and then right click the item and select the Workflow, titled, Test Basic Action. The workflow then executes and places the definition in the definition column.

Figure - Example of SharePoint List with the Workflow enabled

Basic Action Example in Visual Studio

The following component diagram illustrates the major elements that make up the solution package used to add a custom action to the Nintex Workflow.

Figure - Component Diagram of the Solution Package for the Custom Action

These items include the following

Component Type Description
Activity C# Class A workflow activity is the fundamental building block of SharePoint 2013 workflows. In Nintex Workflow 2013, a workflow action adapts a workflow activity for use in Nintex workflows.
Adapter C# Class A workflow action adapter provides the interaction layer between a workflow activity and Nintex Workflow 2013, as well as supporting Nintex-specific features for workflow actions.
NWA File XML File An action definition file is a text file that contains an XML fragment which provides the metadata necessary to associate a workflow action adapter to a workflow activity in Nintex Workflow 2013, and to present information about the resulting custom workflow action in the Workflow designer.
Feature/Event Receiver SharePoint Feature and C# Class The feature is added to the SharePoint solution project containing the workflow action adapter, and an event receiver is added to the feature to interact with Nintex Workflow 2013 object model.

Configuration Dialog

ASPX page

Each workflow action adapter has a corresponding configuration page, an ASP.NET (.aspx) web page displayed by the Workflow designer, so that the user can interactively configure the workflow action.

The Visual Studio Solution File

You can open the example BasicAction solution to review the components that are in the in a complete solution. In our walkthrough we will build these items step-by-step; however feel free to review the example.

Figure - The Custom Action Solution Package

The following table contains an inventory of the elements that must be in place to deploy a functional custom action for Nintex Workflow.

Item Type Description
SolutionNameActivity.cs C# Class A workflow activity is the fundamental building block of SharePoint 2013 workflows. The core action is found in the activity class.
SolutionNameAdapter.cs C# Class A workflow action adapter provides the interaction layer between a workflow activity and Nintex Workflow 2013. The adapter class hooks the function into the workflow.

Layouts\NintexWorkflow\_

CustomActions\BasicAction

 folder This folder (BasicActions) contains the icons and assetts used in the Workflow designer and is copied to the Hive.

SolutionNameDialog.aspx

ASPX page

Each value will be added on the configuration page, in the adapter, and the action itself. Thus a value set in the configuration page will handed to the function, where it can be processed, and then the return value will be passed back to a value exposed on the configuration page.

SolutionNameDialog.aspx.cs

ASPX code behind

Register user controls and server controls for JavaScript.

SolutionName\Images\Icon

 png 30 x 30 pixels
SolutionName\Images\ToolboxIcon png 49 x 49 pixels

NWAFile\SolutionName.nwa

XML File

The NWA file provides the meta definition of the assemblies, graphics, configuration page and so on for the action.

Features\*.feature

SharePoint Feature

The SharePoint Feature and the even receiver handle the deployment and retraction of the feature form your SharePoint environment.

Features\*.feature\*.EventReceiver.cs

C# class

class handles events raised during feature activation, deactivation, installation, uninstallation, and upgrade.

Features\*.feature\*action.Template.xml

XML file

Part of the feature definition.

The hive is located on the SharePoint server and may have the following URL:

C:\Program Files\Common Files\microsoft shared\Web Server Extensions\15\TEMPLATE\LAYOUTS

Your layout assets will be copied to:

C:\Program Files\Common Files\microsoft shared\Web Server Extensions\15\TEMPLATE\LAYOUTS\NintexWorkflow\CustomActions\BasicAction

The BasicAction folder will contain the following structure:

Related information

Working with the BasicAction custom action