Creating the action definition file

An action definition (.nwa) file is a text file that contains an XML fragment which represents the metadata needed by Nintex Workflow 2013 export (.nwp) file to associate a workflow activity to a workflow action adapter for a custom workflow action, and to display information about the resulting custom workflow action. The information in the action definition file is written to the Nintex Workflow configuration database.

The action definition file should be created after implementing the workflow activity, the custom workflow action adapter, and the configuration page. The action definition file links these three components together to define the custom workflow action in Nintex Workflow 2013.

For more information about the contents of the action definition file, see Action Definition File XML Reference.

The following actions must be performed in the action definition file to properly define a custom workflow action:

Identifying the workflow activity

The ActivityAssembly and ActivityType elements identify, respectively, the assembly and class in which the workflow activity is implemented. Nintex Workflow 2013 uses this information to dynamically instantiate the workflow activity when the corresponding custom workflow action is used in a workflow.

The ActivityAssembly element contains the four-part assembly name of the assembly for the workflow activity, as shown in the following example:

<ActivityAssembly>MyCompany.WorkflowActivities, Version=1.0.0.0, Culture=neutral, PublicKeyToken=e5daa473dcec272b</ActivityAssembly>

The assemblies for both the workflow activity and the workflow action adapter must be strongly-named, so the four-part assembly name is used to explicitly identify the assembly within the Global Assembly Cache (GAC). For more information about signing an assembly with a strong name, see How to: Sign an Assembly with a Strong Name.

Similarly, the ActivityType element contains the full name of the class, including the namespace, in which the workflow activity is implemented, as shown in the following example:

<ActivityType>MyCompany.WorkflowActivities.ExecuteSqlActivity</ActivityType>

The identified class must include the Activity class as a base type. For example, the full name of a class in a SharePoint workflow activity that uses the Activity base type, or a class in a custom Nintex workflow activity that uses the ProgressTrackingActivity class, which in turn uses the Activity class as a base type, is acceptable as the value specified in the ActivityType element.

Note: Nintex recommends that you do not directly use the Activity class. Instead, use the ProgressTrackingActivity class in the class that implements your custom workflow activity.

Identifying the workflow action adapter

The AdapterAssembly and AdapterType elements identify, respectively, the assembly and class in which the workflow action adapter is implemented. As with the workflow activity, Nintex Workflow 2013 uses this information to dynamically instantiate the workflow action adapter when the corresponding custom workflow action is used in a workflow.

The AdapterAssembly element contains the four-part assembly name of the assembly for the workflow action adapter, as shown in the following example:

<AdapterAssembly>MyCompany.NintexWorkflowActions, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8e8490bab64b4ec6</AdapterAssembly>

The AdapterType element contains the full name of the class, including the namespace, in which the workflow action adapter is implemented, as shown in the following example:

<AdapterType>MyCompany.NintexWorkflowActions.ExecuteSqlActionAdapter</AdapterType>

The identified class must include the IActionAdapter interface as a base type. For example, the full name of a class in a workflow action adapter that uses the GenericRenderingAction abstract class as a base type, which in turn inherits from the IActionAdapter interface, is acceptable as the value specified in the AdapterType element.

Note: Nintex recommends that you do not directly use the IActionAdapter interface. Instead, use the GenericRenderingAction abstract class in the class that implements your custom workflow action adapter.

Identifying the workflow action

Once the workflow activity and workflow action adapter have been identified for the custom workflow action, you can use the Category, Description, Name, and ToolboxIcon elements to identify the workflow action in Nintex Workflow 2013.

In the Workflow designer, the Category element determines the name of the group in the Controls Toolbox in which the workflow action is placed. If the group does not already exist, a new group is created and the workflow action is added to it when the Workflow designer is displayed.

The Name element identifies the workflow action in the Workflow designer, and is both displayed under the icon of the workflow action in the Controls Toolbox and specified as the default value for the action title of the workflow action on the design canvas.

The Description element provides a human-readable description of the workflow action, displayed as a tooltip when the mouse pointer hovers over the workflow action in the Controls Toolbox.

The ToolboxIcon element specifies the relative URL of the image to display when the workflow action is displayed in the Controls Toolbox of the Workflow designer. The URL is relative to the SharePoint root website, similar to other root website-relative URLs for images in SharePoint 2013, as shown in the following example:

<ToolboxIcon>/_layouts/NintexWorkflow/CustomActions/ExecuteSqlAction/Images/ExecuteSqlActionIconSmall.png</ToolboxIcon>

The following image illustrates how the values of these four elements are used in the Controls Toolbox of the Workflow designer:

Interacting with the workflow action

The remaining elements in the action definition file provide interactivity information for displaying and configuring the workflow action in Nintex Workflow 2013.

Displaying the workflow action

The DocumentLibrariesOnly, Icon, ShowInCommonActions, and WarningIcon elements provide information needed by the Workflow designer to determine how and when to display a workflow action in the Controls Toolbox and design canvas of the Workflow designer.

The DocumentLibrariesOnly element indicates whether a workflow action applies only to workflows associated with a SharePoint document library. If the value of this element is set to "yes" or "true", the workflow action is displayed in the Controls Toolbox only if the list workflow or reusable workflow displayed in the Workflow designer is associated with a SharePoint document library. The workflow action is not displayed for site workflows, reusable workflows, or list workflows associated with SharePoint lists.

The ShowInCommonActions element indicates whether a workflow action can be displayed in the Commonly Used group of the Controls Toolbox in the Workflow designer. If the value of this element is set to "yes" or "true", then the workflow action is displayed in that group, as well as in the group specified in the Category element.

The Icon element specifies the relative URL of the image to display when the workflow action is displayed on the design canvas of the Workflow designer. The URL is relative to the SharePoint root website, as shown in the following example:

<Icon>/_layouts/NintexWorkflow/CustomActions/ExecuteSqlAction/Images/ExecuteSqlActionIcon.png</Icon>

The WarningIcon element optionally specifies the relative URL of the image to superimpose over the workflow action in the design canvas of the Workflow designer when the ValidateConfig method of the workflow action adapter returns false. If a warning icon isn't specified, Nintex Workflow 2013 provides a default warning icon. The URL is relative to the SharePoint root website, as shown in the following example:

<WarningIcon>/_layouts/NintexWorkflow/CustomAction/ExecuteSqlAction/Images/WarningIcon.png</WarningIcon>

The following image illustrates how the values of the Icon and WarningIcon elements are used in the design canvas of the Workflow designer:

Configuring the workflow action

The ConfigurationDialogUrl and HandlerUrl elements identify the relative URLs of, respectively, the configuration page and the ASP.NET generic web handler for the workflow action.

The configuration page is displayed by the Workflow designer when Configure is clicked in the context menu item for the workflow action in the design canvas. The ConfigurationDialogUrl element provides the relative URL to the configuration page, as shown in the following example:

<ConfigurationDialogUrl>CustomActions/ExecuteSqlAction/ExecuteSqlActionDialog.aspx</ConfigurationDialogUrl>

The Visual Studio 2012 template included with the Nintex Workflow 2013 SDK for workflow action adapters provides the expected folder structure, relative to the Layouts mapped folder, and a configuration page in which to work. For more information about the configuration page, see Configuration pages.

The HandlerUrl element provides the relative URL to the ASP.NET generic web handler (.ashx) for the workflow action. Custom workflow actions should use the ActivityServer.ashx web handler, which in turn uses the ActivityServer class, in the Nintex.Workflow.ApplicationPages.Activities namespace, to synchronously process requests for workflow actions, workflow snippets, and workflow templates. The following example shows the value you should use in the HandlerUrl element:

<HandlerUrl>ActivityServer.ashx</HandlerUrl>

Providing localized values

At present, the action definition file does not support localized values. Nintex Workflow 2013 assumes that the values specified for the following elements are provided for the default locale ID, 1033 (US-English):

However, the AddLocalizedResources method of the ActivityReference class can be used to add localized values for these elements, as well as search keywords, to a custom workflow action during deployment. The DeployWorkflowActionWithFeature sample, included with Nintex Workflow 2013 SDK, provides an example of how to add localized values for a custom workflow action.

See Also

Concepts

Workflow activities

Workflow action adapters

Configuration pages

Operations

Working with workflow actions

Working with workflow activities

Reference

Action Definition File XML Reference

.NET Framework Reference