Design the functionality of your custom action

This topic discusses getting your environment set up and preparing the functionality for your action to add to the Nintex Workflow as a custom action.

You will need a SharePoint and Nintex Workflow development environment installed before your begin to code your custom action. This process will leverage the existing SDK templates. In addition, you will want to create a prototype of your action so that you have an inventory of input parameters and the output parameters. You will need to take additional steps in implementing an action with multiple outputs.

To prepare for creating your custom action

1. Set up your NintexWorkflow SDK

2. Design your action

Set up your NintexWorkflow SDK

Set up your NintexWorkflow SDK development environment. For more information see Set up a Nintex Platform Development Environment.

Design your action

You will want to have an understanding of how your action will work before your create your action and add it to Nintex Workflow.

The simplest way to think of an action is that an action has an input, does something to the input, and then produces an output. For instance, a photocopier takes ink toner, blank paper, an original piece of paper, and specified number of copier. The photocopier then produces the number of specified copies. In our example, we include a call to the Merriam Websters API. The action takes a word, a target workflow variable, and an API key. The action then produces a definition and adds it to the specified workflow variable.

Figure - Input, Process, Output Result

An activity is the fundamental building block of a workflow. An action is very similar to a function. A function is a set of inputs, a procedure that transforms those inputs, and then a set of outputs. You might say that a function has an input and produces an output. In C#, a function is represented by the method of a class. The method contains a series of statements. A method has an access level, a return value (the output), the name of the method, and any method parameters (an input).

In addition, the execution logic of an activity fulfills a contract that exists between the activity and the workflow. You must document the execution logic of the activity in a method (which contains the functional core of the activity). While the execution itself is hidden from the workflow developer who includes the activity in a workflow, the execution logic is part of a contract that exists strictly between the workflow and the activity.

An activity defines a set of properties and events, such as any class, along with execution logic that defines the activity's run-time behavior. A set of additional components can be associated with an activity. These include, but are not limited to a validator, a code generator, and custom serializer.

The following class diagram shows the structure of the BasicAction action solution. The action is contained in the WebCallAction class. The class takes the two parameters: a string that contains the word, and the string that contains API Key required by the dictionary API. The action then constructs the API URL, retrieves an XML definition for the word, returns the first definition. As you can see in the diagram, the essentially functionality of the action is contained in a single class with three methods. The rest of the code in the solution is for establishing the action in the Nintex Workflow and SharePoint context. The WebCallAction class is instantiated by the Execute method in the activity class. The other classes are required to place the action in the context of the Nintex Workflow, and to collect the input parameters from the workflow configuration page, and where to place the output of the action process.

Figure - Custom Action Solution Class Diagram

When setting up your own custom action most of the code from the Nintex Workflow SDK can be used as it is. You will thread your parameters through the activity and adapter class. You will also add these parameters to the configuration page where a user can define them in the Workflow designer. These parameters are contained in the fields and properties listed in the class diagram as APIKey, NewWord, and OutDef.

BasicAction Development Example

You can create a prototype of the core function for your action before integrating it with Nintex Workflow. In this example, the WebCallAction class can be run from a console application. The console application uses the ConsoleTest namespace and contains two classes, the WebCallAction class that contains the functionality to be integrated with Nintex Workflow and the Program class that contains the Main method.

Isolating the functionality of the action in its own class allows you to develop the code in an isolated environment, and to gain an understanding of the data input and output for your functionality.

In this case, the class that contains my action takes the following the parameters:

The class will output the following parameter:

WebCallAction Class

 
using System;
using System.IO;
using System.Net;
using System.Xml;

namespace ConsoleTest
{
    internal class WebCallAction
    {
        public static string RootUrl = "http://www.dictionaryapi.com/api/v1/references/collegiate/xml/";

        public string MakeCall(string CallWord, string ApiKey)
        {
            try
            {
                var WordDef = MakeRequest(CallWord, ApiKey);
                return WordDef;
            }
            catch (Exception e)
            {
                return e.Message;
            }
        }

        public static string MakeRequest(string inWord, string ApiKey)
        {
            try
            {
                var request = WebRequest.Create(RootUrl + inWord + ApiKey) as HttpWebRequest;
                var response = request.GetResponse() as HttpWebResponse;

                var xmlDoc = new XmlDocument();
                xmlDoc.Load(response.GetResponseStream());
                var returnword = xmlDoc.SelectSingleNode("//entry[1]/def/dt[1]").InnerText;

                return returnword;
            }
            catch (Exception e)
            {
                var xmlDoc = new XmlDocument();
                var elem = xmlDoc.CreateElement("error");
                elem.InnerText = e.Message;
                var errorword = XmltoString(xmlDoc);

                return errorword;
            }
        }

        public static string XmltoString(XmlDocument input)
        {
            var stringWriter = new StringWriter();
            var xmlTextWriter = new XmlTextWriter(stringWriter);
            input.WriteTo(xmlTextWriter);
            var output = stringWriter.ToString();

            return output;
        }
    }
}
 

                

Program Class

 
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace ConsoleTest
{
    class Program
    {
        static void Main(string[] args)
        {
            string resolvedNewWord = "lake";
            string resolvedAPIKey = "?key=20a4db2b-4dc4-4d07-be23-fabc835e9055";
            string resolvedOutDef = "";

            WebCallAction webster = new WebCallAction();
            string defword = webster.MakeCall(resolvedNewWord, resolvedAPIKey);
            resolvedOutDef = defword;
            Console.Write(resolvedOutDef);
        }
    }
}
 

                

Related information

How to create a custom action