Supporting the Run Now feature
In Nintex Workflow 2013, the Run Now feature allows a user to test a workflow action from within the Workflow designer, without the need to publish the workflow first. If the workflow action supports the Run Now feature, the Run Now button is displayed in the ribbon for the action configuration dialog.
Clicking the Run Now button displays the Run Now Configuration dialog, which in turn displays the configuration settings needed to immediately run the workflow action. The user can provide additional information, if needed, and then click the Execute button in the Run Now Configuration dialog to immediately run the workflow action.
For more information about the Run Now feature, see the Nintex Workflow 2013 product documentation.
To support the Run Now feature in a custom workflow action, you must perform the following actions:
Defining configuration settings
The configuration settings required to immediately execute the workflow action must be defined and configured in the GetDefaultConfig method of the workflow action adapter class, derived from the GenericRenderingAction base class. This is done by setting the values of the DisplayName and RunNowOptions properties of each ActivityParameter object for each activity parameter that represents an input for the corresponding workflow activity. For more information about implementing the GetDefaultConfig method, see Implementing the workflow action adapter.
The DisplayName property represents the name displayed for the configuration setting in the Run Now Configuration dialog, while the RunNowOptions property represents how the configuration setting is rendered in the Run Now Configuration dialog. The RunNowOptions property is an instance of the RunNowParameterOptions object, which allows you to set the following properties for the configuration setting:
-
If the Button property is set to an instance of a RunNowParameterButton object, a button is displayed on the Run Now Configuration dialog. When the button is clicked, the ExecuteRunNow method is invoked, and the CommandKey property of the RunNowContext object passed to the method is set to the value of the CommandKey property of the RunNowParameterButton.
The effect is that the custom workflow action can perform other actions, such as testing a connection, within the ExecuteRunNow method, without actually running the custom workflow action. For more information about using command keys, see Implementing the IRunNow interface.
-
Set the ControlType property to a valid RunNowControlType enumeration value to determine the control displayed for the configuration setting on the Run Now Configuration dialog. If this property is not specified, the default value is set to RunNowControlType.SingleLine.
-
The value of the DisplayIndex property determines the order in which a configuration setting is displayed on the Run Now Configuration dialog.
-
Set the GroupWithPrevious property to true to disable the horizontal line that separates the current configuration setting from the previous configuration setting, visually grouping them together, when displayed on the Run Now Configuration dialog.
-
Set the Required property to true to indicate that the configuration setting displayed on the Run Now Configuration dialog is required, and to display an asterisk (*) character after the name displayed for the configuration setting.
The following code sample illustrates how to set ActivityParameter objects to be displayed on the Run Now Configuration dialog.
public override NWActionConfig GetDefaultConfig(GetDefaultConfigContext context)
{
NWActionConfig c = new NWActionConfig(this);
c.Parameters = new ActivityParameter[5];
c.Parameters[0] = new ActivityParameter();
c.Parameters[0].Name = "ConnectionString";
c.Parameters[0].PrimitiveValue = new PrimitiveValue();
c.Parameters[0].PrimitiveValue.Value = string.Empty;
c.Parameters[0].PrimitiveValue.ValueType = "Text";
// This parameter is displayed as a RunNowControlType.SingleLine control, labeled
// "Connection string", and marked as required.
c.Parameters[0].DisplayName = "Connection string";
c.Parameters[0].RunNowOptions = new RunNowParameterOptions() { Required = true };
c.Parameters[1] = new ActivityParameter();
c.Parameters[1].Name = "Username";
c.Parameters[1].PrimitiveValue = new PrimitiveValue();
c.Parameters[1].PrimitiveValue.Value = string.Empty;
c.Parameters[1].PrimitiveValue.ValueType = "Text";
// This parameter is displayed as a RunNowControlType.Username control, labeled
// "Username", and grouped with the previous parameter.
c.Parameters[1].DisplayName = "Username";
c.Parameters[1].RunNowOptions = new RunNowParameterOptions(){
ControlType = RunNowControlType.Username, GroupWithPrevious = true };
c.Parameters[2] = new ActivityParameter();
c.Parameters[2].Name = "Password";
c.Parameters[2].PrimitiveValue = new PrimitiveValue();
c.Parameters[2].PrimitiveValue.Value = string.Empty;
c.Parameters[2].PrimitiveValue.ValueType = "Text";
// This parameter is displayed as a RunNowControlType.Password control, labeled
// "Username", and grouped with the previous parameter. A button labeled
// "Test connection" is displayed with the control that, when clicked, invokes
// ExecuteRunNow and sets the CommandKey property of the RunNowContext
// object to "TestConnection".
c.Parameters[2].DisplayName = "Password";
c.Parameters[2].RunNowOptions = new RunNowParameterOptions() {
ControlType = RunNowControlType.Password, GroupWithPrevious = true,
Button = new RunNowParameterButton() {
Text = "Test connection", CommandKey = "TestConnection" } };
c.Parameters[3] = new ActivityParameter();
c.Parameters[3].Name = "Query";
c.Parameters[3].PrimitiveValue = new PrimitiveValue();
c.Parameters[3].PrimitiveValue.Value = string.Empty;
c.Parameters[3].PrimitiveValue.ValueType = "Query";
// This parameter is displayed as a RunNowControlType.MultiLine control, labeled
// "Query", and is separated from the previous parameter by a horizontal line.
c.Parameters[3].DisplayName = Properties.Resources.ContentParameterName;
c.Parameters[3].RunNowOptions = new RunNowParameterOptions() { ControlType = RunNowControlType.MultiLine };
// This parameter is not displayed in the Run Now Configuration dialog.
c.Parameters[4] = new ActivityParameter();
c.Parameters[4].Name = "Output";
c.Parameters[4].Variable = new NWWorkflowVariable();
c.Parameters[4].Variable.Type = "Text";
c.TLabel = ActivityReferenceCollection.FindByAdapter(this).Name;
return c;
}
Implementing the IRunNow interface
The Run Now feature is supported in a custom workflow action by implementing the IRunNow interface for the workflow action adapter class. Add the IRunNow interface to the class declaration for the workflow action adapter class and explicitly implement the interface, as illustrated in the following code example:
public class SampleActionAdapter : GenericRenderingAction, IRunNow
{
bool IRunNow.AdministratorControlled
{
get { return true; }
}
RunNowResult IRunNow.ExecuteRunNow(RunNowContext context)
{
}
}
The IRunNow interface requires the implementation of the following members, as shown in the previous code example:
-
The AdministratorControlled property, which indicates whether the Run Now feature for the workflow action is controlled by the Allow 'Run now' on actions that interact with external data global setting.
-
The ExecuteRunNow method, which is invoked when the Execute button is clicked from the ribbon of the Run Now Configuration dialog.
Implementing the AdministratorControlled property
If the workflow action interacts with external data, or can perform operations involving external systems, then implement the AdministratorControlled property so that it returns true. If the workflow operation interacts only with data within the context of the workflow, then the property can return false.
Implementing the ExecuteRunNow method
The ExecuteRunNow method does not execute the workflow activity itself. Ideally, the ExecuteRunNow method invokes the same code invoked by the Execute method of the workflow activity, to ensure that the behavior in the Run Now Configuration dialog and in the workflow is exactly the same. However, that may not be possible if you do not have access to the code for the workflow activity, so you may need to provide code that, as closely as possible, performs the same tasks as the workflow activity.
When invoked by the Run Now Configuration dialog, the ExecuteRunNow method receives a RunNowContext object as a parameter. The RunNowContext object provides access to the SPWeb and SPSite objects on which the workflow action is being executed, a NWActionConfig object containing the configuration of the workflow action as configured in the Run Now Configuration dialog, and a command key to identify which command executed the ExecuteRunNow method. If the command key, represented by the CommandKey property, is set to an empty string (""), then the Execute button in the ribbon of the Run Now Configuration dialog was clicked to invoke the ExecuteRunNow method; otherwise, a RunNowParameterButton for one of the activity parameters was clicked, and its command key was passed to the RunNowContext object.
After execution, the ExecuteRunNow method returns a RunNowResult object, in which the Data property is set to a string representing the results of the method.
The following code example illustrates an implementation of the ExecuteRunNow method.
RunNowResult IRunNow.ExecuteRunNow(RunNowContext context)
{
string executionResult = null;
switch (context.CommandKey)
{
case "TestConnection":
// Run a method named TestConnection, using the values of the
// ConnectionString, Username, and Password activity parameters.
if (this.TextConnection(
context.ParameterHelpers["ConnectionString"].Value,
context.ParameterHelpers["Username"].Value,
context.ParameterHelpers["Password"].Value))
{
executionResult = "Connection succeeded";
}
else
{
executionResult = "Connection failed";
}
break;
default:
// Run a method named RunQuery, using the values of the
// ConnectionString, Username, Password, and Query activity parameters.
executionResult = this.RunQuery(
context.ParameterHelpers["ConnectionString"].Value,
context.ParameterHelpers["Username"].Value,
context.ParameterHelpers["Password"].Value,
context.ParameterHelpers["Query"].Value);
break;
}
// Return a RunNowResult object with the results.
return new RunNowResult() { Data = executionResult };
}
Displaying the Run Now button on the configuration page
To display the Run Now button on the ribbon of the configuration settings dialog, the AllowRunNow property of the DialogBody control, contained in the ContentBody control in the configuration page for the custom workflow action, must be set to either RunNowMode.EnableAlways or RunNowMode.EnableAdministratorControlled. For more information about configuring the DialogBody control, see Working with the ContentBody control.
See Also
Concepts
Operations
Working with workflow activities