Implementing the workflow action adapter
Workflow action adapters provide the interaction layer between workflow activities and Nintex Workflow 2013 export (.nwp) file, as well as supporting Nintex-specific features for workflow actions. If the custom workflow action adapter references a custom workflow activity, you must develop the custom workflow activity first. For more information about developing a custom workflow activity, see Working with workflow activities.
Once you have either identified an existing workflow activity or developed a custom workflow activity, developing your custom workflow action adapter typically involves the following steps:
Creating the Visual Studio 2012 project
You can use the Workflow Action Adapter project template, included with Nintex Workflow 2013 SDK, to create a new Visual Studio 2012 project for your custom workflow action adapter. Once the project is created, you can then modify the included class, already derived from the GenericRenderingAction class, to implement your workflow action adapter. For more information about the Workflow Action Adapter project template, see Installing and using Visual Studio templates.
For more information about creating Visual Studio 2012 solutions and projects, see Creating Solutions and Projects.
Tip: Nintex recommends that you first use the Workflow Action Adapter project template to create a Visual Studio 2012 solution for your workflow action adapter, and then use the Workflow Activity project template to add a new Visual Studio 2012 project for your workflow activity to that solution, for convenience when referencing the workflow activity from the workflow action adapter. For more information, see Implementing the workflow activity.
Creating the workflow action adapter class
The public class that implements the GenericRenderingAction class is referred to throughout this documentation as the workflow action adapter class. The Workflow Action Adapter project template provides both the necessary references and a starting workflow action adapter class for the Visual Studio 2012 project.
Implementing the GetDefaultConfig method
The workflow action adapter determines the default configuration used by the custom workflow action, by overriding the GetDefaultConfig method of the GenericRenderingAction class. In the GetDefaultConfig method, a NWActionConfig object is constructed and returned, to provide default configuration information to Nintex Workflow 2013 when the custom workflow action is instantiated for a workflow.
The following code example illustrates a sample implementation of the GetDefaultConfig method.
public override NWActionConfig GetDefaultConfig(GetDefaultConfigContext context)
{
// Instantiate the NWActionConfig object that represents the default
// configuration for the workflow action.
NWActionConfig config = new NWActionConfig(this);
// Build the default configuration for the workflow action, by
// populating an array of ActivityParameters, each of which represents
// a single activity parameter.
// TODO: Instantiate and configure an ActivityParameter object for each
// dependency property.
// If this custom workflow action supports error handling or multiple output,
// add any necessary code here.
// Set the default top label text for the workflow action.
config.TLabel = ActivityReferenceCollection.FindByAdapter(this).Name;
// Return the default configuration.
return config;
}
Building the default configuration
The Parameters property of the NWActionConfig object contains an array of ActivityParameter objects, each of which represents an activity parameter. In a default configuration for a workflow action, an activity parameter can represent either a primitive value or a workflow variable, determined by setting the value of either the PrimitiveValue or Variable property, respectively. Primitive values represent a value supplied by a user, including inserted workflow reference, while workflow variables represent a workflow variable selected from a list, such as a VariableSelector user control on a configuration page.
The following code example illustrates how to create an ActivityParameter that represents a string primitive value.
config.Parameters[0] = new ActivityParameter(); config.Parameters[0].Name = "Name"; config.Parameters[0].PrimitiveValue = new PrimitiveValue(); config.Parameters[0].PrimitiveValue.Value = string.Empty; config.Parameters[0].PrimitiveValue.ValueType = SPFieldType.Text.ToString();
The following code example illustrates how to create an ActivityParameter that represents a string workflow variable. You will want to use this if you are planning on storing your output value in a Workflow variable.
config.Parameters[0] = new ActivityParameter(); config.Parameters[0].Name = "Output"; config.Parameters[0].Variable = new NWWorkflowVariable(); config.Parameters[0].Variable.Type = SPFieldType.DateTime.ToString();
Supporting the Run Now feature
If the workflow action supports the Run Now feature, additional information must be supplied for each defined ActivityParameter, to describe how to render the activity parameter on the Run Now Configuration dialog. For more information about supporting the Run Now stor, see Supporting the Run Now feature.
Supporting error handling and multiple output
Additional code must be added to the GetDefaultConfig method to support error handling and multiple output, if required by the custom workflow action. For more information about supporting error handling and multiple output, see Supporting error handling and Supporting multiple output, respectively.
Implementing the GetConfig method
The workflow action adapter determines the current configuration used by the custom workflow action, by overriding the GetConfig method of the GenericRenderingAction class. In the GetConfig method, a NWActionConfig object is retrieved by invoking the GetDefaultConfig method, populated with values retrieved from the associated workflow activity, and returned, to provide current configuration information to Nintex Workflow 2013 when the custom workflow action is rendered.
The following code example illustrates a sample implementation of the GetConfig method.
public override NWActionConfig GetConfig(RetrieveConfigContext context)
{
// Retrieve the default configuration, by invoking the GetDefaultConfig
// method using the current context.
NWActionConfig config = this.GetDefaultConfig(context);
// Prepare a keyed collection of ActivityParameterHelper objects.
Dictionary<string, ActivityParameterHelper> parameters =
config.GetParameterHelpers();
// TODO: For each property, retrieve and update the values in the configuration.
//parameters[PropertyName].RetrieveValue(context.Activity,
// ActivityClass.PropertyNameProperty, context);
// If this custom workflow action supports error handling or multiple output,
// add any necessary code here.
// Return the configuration.
return config;
}
Building the current configuration
The ActivityParameterHelper helper class provides a set of utility methods for working with an ActivityParameter object. For the GetConfig method, a Dictionary collection containing an ActivityParameterHelper for each ActivityParameter defined in the default configuration retrieved from the GetDefaultConfig method is created by invoking the GetParameterHelpers method of the NWActionConfig object representing the default configuration.
For each appropriate activity parameter, the RetrieveValue method of the corresponding ActivityParameterHelper object in the collection is invoked to retrieve the value of the public property that represents the corresponding dependency property from the workflow activity.
The following code example illustrates a typical RetrieveValue invocation, to populate the ActivityParameter named Name with the value of the Name property from the SampleActivity workflow activity.
parameters["Name"].RetrieveValue(context.Activity, SampleActivity.Name, context);
Supporting error handling and multiple output
Additional code must be added to the GetConfig method to support error handling and multiple output, if required by the custom workflow action. For more information about supporting error handling and multiple output, see Supporting error handling and Supporting multiple output, respectively.
Implementing the ValidateConfig method
The workflow action adapter validates the current configuration used by the custom workflow action, by overriding the ValidateConfig method of the GenericRenderingAction class. In the ValidateConfig method, a NWActionConfig object is retrieved from the ActivityContext object passed to the method, the appropriate ActivityParameter objects are validated, and the method returns a Boolean value that indicates whether the current configuration is valid to Nintex Workflow 2013, to determine how to render the custom workflow action.
The following code example illustrates a sample implementation of the ValidateConfig method.
public override bool ValidateConfig(ActivityContext context)
{
bool isValid = true;
// Prepare a keyed collection of ActivityParameterHelper objects.
Dictionary<string, ActivityParameterHelper> parameters =
context.Configuration.GetParameterHelpers();
// TODO: Invoke the Validate method for each ActivityParameterHelper.
// If this custom workflow action supports error handling or multiple output,
// add any necessary code here.
// Return whether the configuration is valid.
return isValid;
}
Validating the current configuration
A Dictionary collection containing an ActivityParameterHelper for each ActivityParameter defined in the current configuration is created by invoking the GetParameterHelpers method of the NWActionConfig object representing the current configuration, retrieved from the Configuration property of the ActivityContext object.
The Validate method of the ActivityParameterHelper object is used to validate the ActivityParameter object, to ensure that the ActivityParameter is both configured correctly (for example, that the name of a workflow variable is set to something other than an empty string) and set to a properly formatted value for the expected data type.
The following code example demonstrates a typical implementation of the Validate method, to validate the ActivityParameter named Name used in previous code examples.
if (!parameters["Name"].Validate(typeof(string), context))
{
isValid &= false;
validationSummary.AddError("Name", ValidationSummaryErrorType.CannotBeBlank);
}
You can provide additional validation logic in the ValidateConfig method, as needed. If an ActionParameter fails validation, the AddError method of the ValidationSummary object, provided by the validationSummary variable from the GenericRenderingAction base class, should be invoked to provide information about the validation error. The information provided by the AddError method is presented in the action summary pane, when rendered, and written to the workflow history and SharePoint logs depending on Nintex Workflow 2013 global settings.
Supporting error handling and multiple output
Additional code must be added to the GetConfig method to support error handling and multiple output, if required by the custom workflow action. For more information about supporting error handling and multiple output, see Supporting error handling and Supporting multiple output, respectively.
Supporting action summaries
If the ValidateConfig method returns false, the action summary pane displayed in the Workflow designer is rendered using the ValidationSummary object. For more information about implementing action summaries, see Implementing action summaries.
Implementing the AddActivityToWorkflow method
The workflow action adapter determines the current configuration used by the custom workflow action, by overriding the AddActivityToWorkflow method of the GenericRenderingAction base class. In the AddActivityToWorkflow method, one of the following two processes should be implemented:
-
An instance of the associated workflow activity is instantiated, configured, and added to the Activities collection of the workflow activity retrieved from the ParentActivity property of the PublishContext object. The AddActivityToWorkflow method then returns null.
-
A new CompositeActivity is instantiated, configured, and added to the Activities collection of the workflow activity retrieved from the ParentActivity property of the PublishContext object. The child activities to be included in the new CompositeActivity are then instantiated, configured, and added to the Activities collection of the new CompositeActivity. The AddActivityToWorkflow method then returns the new CompositeActivity.
The first process is the most commonly implemented form of the AddActivityToWorkflow method. The second process is typically implemented only if a dynamically defined CompositeActivity is necessary to perform complex actions.
The following code example illustrates a sample implementation of the AddActivityToWorkflow method, using the first process.
public override CompositeActivity AddActivityToWorkflow(PublishContext context)
{
// Prepare a keyed collection of ActivityParameterHelper objects.
Dictionary<string, ActivityParameterHelper> parameters =
context.Config.GetParameterHelpers();
// TODO: Instantiate the workflow activity.
//SampleActivity activity = new SampleActivity();
// TODO: Assign the activity parameter values to the workflow activity.
//parameters[PropertyName].AssignTo(activity, SampleActivity.PropertyNameProperty, context);
// TODO: Set standard context items for the workflow activity.
//activity.SetBinding(SampleActivity.__ContextProperty, new ActivityBind(context.ParentWorkflow.Name, StandardWorkflowDataItems.__context));
//activity.SetBinding(SampleActivity.__ListItem, new ActivityBind(context.ParentWorkflow.Name, StandardWorkflowDataItems.__item));
//activity.SetBinding(SampleActivity.__ListId, new ActivityBind(context.ParentWorkflow.Name, StandardWorkflowDataItems.__list));
// If this custom workflow action supports error handling,
// add any necessary code here.
// TODO: Assign values for common properties from the configuration to the workflow activity.
//ActivityFlags f = new ActivityFlags();
//f.AddLabelsFromConfig(context.Config);
//f.AssignTo(activity);
// TODO: Add the workflow activity to the parent workflow activity for the context.
//context.ParentActivity.Activities.Add(activity);
// If this custom workflow action supports multiple output,
// add any necessary code here.
return null;
}
Assigning configuration values to the workflow activity
A Dictionary collection containing an ActivityParameterHelper for each ActivityParameter defined in the current configuration is created by invoking the GetParameterHelpers method of the NWActionConfig object representing the current configuration, retrieved from the Config property of the PublishContext object passed to the AddActivityToWorkflow method.
For each appropriate activity parameter in the current configuration of the workflow action adapter, the AssignTo method of the corresponding ActivityParameterHelper object in the collection is invoked to set the value of the public property that represents the corresponding dependency property from the workflow activity to the value of the activity parameter.
The following code example demonstrates a typical implementation of the AssignTo method, to assign the value of the ActivityParameter named Name to the corresponding public property that represents the dependency property named Name in the workflow activity.
parameters["Name"].AssignTo(activity, SampleActivity.Name, context);
Binding context items from the workflow activity
The SetBinding method of the DependencyObject base class, from the workflow activity, is invoked to bind the public properties that represent the standard dependency properties implemented by the workflow activity to the corresponding context items provided by the workflow. The StandardWorkflowDataItems helper class is used to identify the names of the context items in the workflow.
The following code example demonstrates a typical implementation of the SetBinding method, to bind the __ContextProperty, __ListItem, and __ListID public properties from the workflow activity to the __context, __item, and __list context items, respectively, from the workflow.
activity.SetBinding(SampleActivity.__ContextProperty, new ActivityBind(context.ParentWorkflow.Name, StandardWorkflowDataItems.__context)); activity.SetBinding(SampleActivity.__ListItem, new ActivityBind(context.ParentWorkflow.Name, StandardWorkflowDataItems.__item)); activity.SetBinding(SampleActivity.__ListId, new ActivityBind(context.ParentWorkflow.Name, StandardWorkflowDataItems.__list));
Other standard context items are available for implementation and binding. For more information, see StandardWorkflowDataItems.
Assigning values for common properties to the workflow activity
The ActivityFlags class represents configuration settings common to all workflow actions. The properties of the ActivityFlags class roughly correspond to the configuration settings in the Labels and Common sections of the configuration settings dialog in the Workflow designer.
The AddLabelsFromConfig method sets the properties of the ActivityFlags class from the current configuration, and then the AssignTo method of the ActivityFlags class serializes the class and sets the Description property of the Activity base class for the workflow activity to the serialized value.
Adding the workflow activity to the workflow
Finally, the Add method of the ActivityCollection object, from the Activities property of the Activity object provided in the ParentActivity property of the PublishContext object, is invoked to add the configured workflow activity to the workflow.
Supporting error handling and multiple output
Additional code must be added to the AddActivityToWorkflow method to support error handling and multiple output, if required by the custom workflow action. For more information about supporting error handling and multiple output, see Supporting error handling and Supporting multiple output, respectively.
Implementing the BuildSummary method
The workflow action adapter, if the ValidateConfig method returns true, determines the content of the action summary pane by overriding the BuildSummary method of the GenericRenderingAction class. The BuildSummary method instantiates and configures an ActionSummary object, using the information provided in the ActivityContext object passed to the method.
The following code example illustrates a sample implementation of the BuildSummary method:
public override ActionSummary BuildSummary(ActivityContext context)
{
string displayMessage = "";
// Prepare a keyed collection of ActivityParameterHelper objects.
Dictionary<string, ActivityParameterHelper> parameters =
context.Configuration.GetParameterHelpers();
// TODO: Construct a display message for the action summary.
//displayMessage = string.Format("Perform an operation using value '{0}'.", parameters[PropertyName].Value);
// Return the action summary.
return new ActionSummary(displayMessage);
}
Supporting action summaries
If the BuildSummary method is invoked, the action summary pane displayed in the Workflow designer is rendered using the ActionSummary object returned by the method. For more information about implementing action summaries, see Implementing action summaries.
Creating the configuration page
The user interface displayed by the Workflow designer in Nintex Workflow 2013 for configuring the workflow action is called the configuration page. The Workflow Action Adapter project template provides the necessary folder structure and a starting ASP.NET page in which you can create the configuration page for your workflow action. For more information about creating a configuration page, see Creating configuration pages.
Creating the assembly
Once the workflow action adapter class is implemented, you can then build the Visual Studio project and create a .NET Framework assembly.
In SharePoint 2013, an assembly that contains a workflow action adapter must be strongly named and installed into the Global Assembly Cache (GAC). Ensure that, before you compile your assembly, that you create a strong name key file and sign the assembly. For more information about signing assemblies, see Creating and Using Strong-Named Assemblies.
See Also
Concepts
Operations
Working with workflow activities