In this post I look at taking a function, adding it to a custom action, and making it available in Nintex Workflow 2013. This is the third post in my series, "Function to Microservice with the Nintex Workflow Platform," which looks at how you can move your function as portable unit in the Nintex Workflow Platform.
I'll walk you through installing a custom action. You can use custom actions to provide the functionality found in many open-source libraries, in your own console applications, or to integrate your workflow data with web services or other remote resources. In this walk through, I'll use the function from the first post in this series. That function uses the Newtonsoft JSON library to convert an XML string into JSON, or to convert a JSON string into XML. We will build out the templates from the Nintex Workflow 2013 Software Development Kit. In a previous post, Create a Custom Action for Nintex Workflow 2013," I looked at creating a custom action that calls the Merriam Webster REST API.
This post isn't going to look at creating a custom control from scratch. For that information you can refer to my previous post and the documentation in the Nintex Workflow 2013 SDK for a detailed overview and steps.
Project links
To download a copy of the project from the Nintex SDK GitHub (JsonXMLConverterAction)
Some other useful links:
Function as a Custom Action
You can add an action in Nintex Workflow from the Workflow actions toolbox, and then configure the action in the designer. We will be adding the JSON/XML converter contained in its own class. The activity class will instantiate the object that contains your function. The maker of the workflow will specify the input string and and output string targeted to a workflow variable to hold the output of the function.
Install the Custom Action
You will need to perform the following steps to install the custom action: open a SharePoint 2013 development environment with Visual Studio, download the code sample, deploy, and then enable the action in the Nintex Workflow Management in SharePoint's Central Administration.
Set Up
You will need the following things in place before you install the action:
- Office and SharePoint SDK for Visual Studio
- Nintex Workflow SDK 2013 installed in Visual Studio
- Nintex Workflow 2013
For information and links on setting up a SharePoint 2013, see "Set up a Nintex Workflow Platform Development Environment" in the SDK.
Steps
- Download the solution file and add to a folder in your SharePoint 2013 development environment.
- Open the solution in Visual Studio.
- Click the project in the Solution Explorer, JsonXMLConverterAction, and select the Site Url for your SharePoint development site in the Properties window.
- Right-click the project in the Solution Explorer, and select Deploy.
- Open the Central Administration, and Manage allowed actions. Click Add a custom action, navigate to the NWA file in the solution folder, and import the file.
- Verify that the action works by building a test workflow.
Notes on the Code
In Nintex Workflow 2013, a workflow action represents the combination of a SharePoint workflow activity and a Nintex Workflow workflow action adapter. Configuration pages, included with the workflow action adapter, provide an interface with which a user can configure the workflow action. The workflow action adapter is associated with the corresponding workflow activity by metadata, stored in the Nintex configuration database.
I will look in more detail about how the custom action code will handle your input. The Custom Action Plumbing section of the diagram above shows the data flow for the input. The input enters the process through the the configuration page, passes to the Adapter Class, and then to the Activity Class, and then the return is passed back tot the SharePoint context. The housekeeping for the action is handled by the Package, NWA file, and Event Receiver displayed in the Nintex Workflow and SharePoint Plumbing section.
When I created the action, I had to set it up so that the configuration window in the Workflow designer would allow the workflow maker to add a string or string variable containing text to convert, and then specify a string variable after the function has converted the input string.
The action uses the following parameters:
| Parameter | Datatype | Description |
|---|---|---|
| Input JSON/XML | String | Will contain the input XML or JSON text. |
| Output stored in | String | Will contain the output XML or JSON text. |
In the configuration window (JsonXMLConverterActionDialog.aspx) at the following location in the package you can find the code that creates the form input:
<script type="text/javascript" language="javascript">
function TPARetrieveConfig() {
setRTEValue('<%=JSONINProperty.ClientID%>', configXml.selectSingleNode("/NWActionConfig/Parameters/Parameter[@Name='JSONIN']/PrimitiveValue/@Value").text);
var drpXMLOUT = document.getElementById("<%=XMLOUTProperty.ClientID %>");
drpXMLOUT.value = configXml.selectSingleNode("/NWActionConfig/Parameters/Parameter[@Name='XMLOUT']/Variable/@Name").text;
}
function TPAWriteConfig() {
configXml.selectSingleNode("/NWActionConfig/Parameters/Parameter[@Name='JSONIN']/PrimitiveValue/@Value").text = getRTEValue('<%=JSONINProperty.ClientID%>');
var drpXMLOUT = document.getElementById("<%=XMLOUTProperty.ClientID %>");
configXml.selectSingleNode("/NWActionConfig/Parameters/Parameter[@Name='XMLOUT']/Variable/@Name").text = drpXMLOUT.value;
return true;
}
onLoadFunctions[onLoadFunctions.length] = function () {
dialogSectionsArray["<%= MainControls1.ClientID %>"] = true;
};
</script>I then add the parameters to the action adapter (JsonXMLConverterActionAdapter.cs), getting closer to the center of the custom action class.
private const string JSONINPropertyName = "JSONIN";
private const string XMLOUTPropertyName = "XMLOUT";
public override NWActionConfig GetDefaultConfig(GetDefaultConfigContext context)
{
NWActionConfig config = new NWActionConfig(this);
config.Parameters = new ActivityParameter[2];
config.Parameters[0] = new ActivityParameter();
config.Parameters[0].Name = JSONINPropertyName;
config.Parameters[0].PrimitiveValue = new PrimitiveValue();
config.Parameters[0].PrimitiveValue.Value = string.Empty;
config.Parameters[0].PrimitiveValue.ValueType = SPFieldType.Text.ToString();
config.Parameters[1] = new ActivityParameter();
config.Parameters[1].Name = XMLOUTPropertyName;
config.Parameters[1].Variable = new NWWorkflowVariable();
config.TLabel = ActivityReferenceCollection.FindByAdapter(this).Name;
return config;
}I add them to the action class (JsonXMLConverterActivity.cs) In this action then I instantiate the object containing my function, feed it my input parameter, and then load the product into my output parameter.
string resolvedJSONIN = ctx.AddContextDataToString(this.JSONIN); // context
// Perform the workflow activity.
try {
JsonConverterAction converter = new JsonConverterAction();
this.XMLOUT = converter.ConvertIt(resolvedJSONIN);
} catch {
// If an exception occurs that should stop the workflow,
// then throw the error.
throw;
}Review the steps, you to begin by wiring your function into the Activity class which contains the execute() method. Then thread the input and output variables from the Configuration Page, through the Adapter class, and back into the Activity Class. Finally you will want to configure the various files required to register your action with Nintex Workflow and your SharePoint environment (the Package, NWA File, and Event Receiver (in the Feature folder). You will deploy your action as a solution to your SharePoint environment, and then register the custom action in the Nintex Workflow Action Management page in Central Administration.
That is more or less how I set it up. For a full explanation of the parts, how to set up your own project, and how to build each section, see my post on creating a custom action or refer to the Nintex Workflow 2013 SDK.
Test Workflow
When we have installed our action, and activated in the Nintex Workflow Manager, we will need to build a workflow to test it out. Converts text from JSON to XML or from XML to JSON. The converter detects the first character in the string and then convert to XML or JSON.
Build a Test workflow
The following workflow shows the JsonXMLConvertAction added to a simple Nintex workflow. The workflow has two variables defined: JSONIN and XMLOUT. (The names are misleading in that you could put in XML and get out JSON...) The first workflow action, Set variable, loads a string from a SharePoint list. And then the JsonXMLConvertActionaction runs the conversion and then adds the conversion to the XMLOut variable. And then the third action, Set field value, inserts the converted text into the definition column in the SharePoint list. In building the workflow, drag the JsonXMLConvertAction from the Custom Action group in the toolbar. And then enable the workflow to start from a list item.
Configure the Json XML Converter Action
You will need the source file as text in a variable or list column, and a variable to store the result of the conversion. Your output variable should be set to a As String(Default) return type.
To configure the Json XML Converter Action
- Insert the variable or list reference the Input JSON/XML box that contains JSON or XML.
- Select the variable that will contain the output of the conversion.
The action can only process JSON that begins with an object.
To see the action in the context of the SharePoint list, I typed a word in the word column, and then right-clicked the item and select the workflow, titled, Test Basic Action. The workflow then executed, and placed the definition in the definition column.
JSON to XML ("{")
The following table shows the conversion with a JSON strong to XML:
| JSON | XML |
|---|---|
| |
XML to JSON ("<")
The following table shows the conversion with an XML string to JSON:
| XML | JSON |
|---|---|
| |
That is our example function placed into a custom action in Nintex Workflow 2013. We've now looked at placing our function in an inline function, and now a custom action. The next two posts will look at encapsulating the function using two different strategies in Nintex Workflow, as a user-defined action, and as workflow that can be accessed as a RESTful endpoint with the External Start feature. Thanks for reading this far. If you are interested in learning more about creating your own custom action to host your function, you read my post, "Create a Custom Action for Nintex Workflow 2013".
