ExecuteSqlScalar sample
The ExecuteSqlScalar sample provides an example of implementing a simple custom action in Nintex Workflow 2013, in which scalar Transact-SQL statements can be executed.
Installing the sample
The sample is included with the Nintex Workflow 2013 SDK as a compressed folder, containing the Visual Studio 2012 solution and associated projects. For more information about installing the sample, see Installing and using Visual Studio samples.
Overview
The sample represents a Nintex workflow action named Execute SQL Scalar, which includes a workflow action adapter named ExecuteSqlScalarAction and a custom SharePoint workflow activity named ExecuteSqlScalarActivity, for use with Nintex Workflow 2013.
The sample also illustrates a typical branding scenario, in which the namespace for the action adapter and the activity contains the name of the company, Crestan, and the custom action itself is displayed in a branded category within the Controls Toolbox of the Workflow designer.
ExecuteSqlScalarActivity activity
The ExecuteSqlScalarActivity custom workflow activity is derived from the ProgressTrackingActivity class. The activity executes a single scalar Transact-SQL statement and returns the resulting scalar value as a string.
The activity implements three custom dependency properties, in addition to the __ListItem, __Context, and __ListId standard dependency properties, as DependencyProperty objects:
| Property | Description |
|---|---|
| ConnectionString |
The connection string used to connect the activity to the specified SQL Server instance. Note: The sample does not support Windows authentication, and assumes that all information needed to connect to a SQL Server instance is present in the connection string. |
| SqlQuery | The Transact-SQL scalar statement to execute on the SQL Server instance. |
| ResultOutput | The string in which the result of the Transact-SQL scalar statement is returned. |
The bulk of the code for this activity is in the Execute method, which overrides the method provided by the Activity base class. The method performs the following steps:
-
Prepares the custom workflow activity for execution, by performing the following steps:
-
Confirms that the activity can be executed on the current SharePoint site, by invoking the IsAllowed method of the ActivityActivationReference class.
-
Gets the current workflow context for the activity, by invoking the GetContext method of the NWWorkflowContext class.
-
Begins progress tracking for the activity, by invoking the LogProgressStart method of the ProgressTrackingActivity class.
-
Resolves the connection string in the ConnectionString dependency property, and any workflow references included in the dependency property, by invoking the AddContextDataToString method of the NWWorkflowContext class for the activity.
-
Resolves the Transact-SQL statement in the SqlQuery dependency property, and any workflow references included in the dependency property, by invoking the AddContextDataToString method of the NWWorkflowContext class for the activity.
Because the dependency property represents a Transact-SQL statement, the GetContextData method of the NWWorkflowContext class for the activity is invoked to ensure that any included workflow reference values are encoded for Transact-SQL.
-
-
Connects to and executes the resolved Transact-SQL statement on the specified SQL Server instance, by performing the following steps:
-
Creates a SqlConnection object to the SQL Server instance, using the resolved connection string.
-
Creates a SqlCommand object, using the resolved Transact-SQL statement.
-
Opens the SqlConnection object, and then executes the SqlCommand object by invoking the ExecuteScalar method.
-
If a result is returned, the value of the ResultOutput dependency property is set to the returned scalar value, converted to a string.
-
-
Closes the custom workflow activity, by performing the following steps:
-
Ends progress tracking for the activity, by invoking the LogProgressEnd method of the ProgressTrackingActivity class.
-
Returns ActivityExecutionStatus.Closed for the Execute method, to indicate to both SharePoint 2013 and Nintex Workflow 2013 that the activity is closed.
-
If any exceptions or faults occur during the execution of the custom workflow activity, the HandleFault method is invoked. This method overrides the HandleFault method of the Activity class, and ensures that faults are reported to Nintex Workflow 2013 by first invoking the HandleFault method of the ActivityErrorHandler class, and then invoking the HandleFault method of the base class.
For more information about creating workflow activities for Nintex Workflow 2013, see Creating workflow activities.
ExecuteSqlScalarAction action
The ExecuteSqlScalarAction custom action provides an implementation of the GenericRenderingAction base class that adapts the ExecuteSqlScalarActivity activity for use within Nintex workflows. The custom action also provides a basic configuration page, which provides a user interface for the action parameters defined for the custom action.
The custom action implements three ActivityParameter objects, which are bound to the custom dependency properties defined in the ExecuteSqlScalarActivity activity:
| Property | Description |
|---|---|
| ConnectionString |
String, bound to the ConnectionString dependency property. Note: The sample does not support Windows authentication, and assumes that all information needed to connect to a SQL Server instance is present in the connection string. |
| SqlQuery | String, bound to the SqlQuery dependency property. |
| Output |
String, bound to the ResultOutput dependency property. |
The bulk of the code for this action is focused around retrieving and validating the configuration for the action, and adding the custom activity to the parent activity for the workflow.
-
The GetDefaultConfig method defines the default configuration, including configuration properties and the default label, for the custom action.
-
The ValidateConfig method validates the configuration properties, as needed, for the custom action.
-
The AddActivityToWorkflow method instantiates and configures the custom activity, binds the configuration properties of the custom action to the dependency properties of the custom activity, and then adds the custom activity to the parent activity for the current workflow.
-
The BuildSummary method returns details about the custom action, in the form of an ActionSummary object. The Nintex Workflow designer displays this summary when the mouse pointer is hovered over the action in the design canvas.
The configuration page, ExecuteSqlScalarActionDialog.aspx, implements three ConfigurationProperty web controls:
-
A SingleLineInput control, which represents the ConnectionString configuration property.
-
A PlainTextWebControl control, which represents the SqlQuery configuration property.
-
A VariableSelector control, which represents the workflow reference that receives the value of the Output configuration property.
Using the sample
This sample does not include an automatic deployment mechanism, and so must be manually deployed before it can be used, or an automatic deployment mechanism can be created for the sample. For more information about manually deploying a custom action, see Deploying workflow actions with Nintex Workflow Management.