emily.billing@nintex.com

Best Practice for Workflow Design - User Defined Actions

Blog Post created by emily.billing@nintex.com Champion on May 12, 2014

What is a User Defined Action?

 

A user defined action is similar to a custom workflow action; it can take certain input variables and output a result. The actions inside the UDA can be hidden from the end user so they will only see a single workflow action that can actually perform a series of workflow actions or a certain task.

This can be useful when re-using a workflow process across multiple sites or for creating a complex set of workflow actions that end users can easily configure and reuse. The UDA appears in the Workflow Designer page, when you create a User Defined Action, this action can be used in the site, site collection or farm.

 

You can think of UDAs as a workflow in a box. Designing a UDA is just the same as designing a workflow. It wraps a bunch of actions inside it, and the UDA can take any number of input and output parameters. When it is published, it will appear in your workflow designer page just as any other action, but the contents of which are hidden from the designer (workflow user).

 

There are a number of reasons to use UDAs.

Reuse

Since we don't want to build the same complex logic more than once, we build it in a UDA and then we can use this in any workflow, rather than having to build it again.

Also, if you make changes to the UDA and publish it, you are given the option to republish and workflows that use this UDA, so they are kept up to date.

 

Hiding logic

You will encounter users that need to build workflows, but their techincal skills are limited.  When it comes to needing data from a database or from a web service call, they may not be able to do this on their own.

A more technical person can build a UDA, put it any database calls or web service calls, expose some parameters and then the business user will be able to use this UDA in their workflows without knowing all the nuts and bolts.

 

Create a User Defined Action

Open the Site Settings, click on Nintex Workflow and then Manage User Defined Actions.

UDA.png

 

You can create, import, export, modify, promote and delete UDAs. You can also analyze a UDA, so that you can tell which workflows are using it.

UDA_settings.png

 

The designer page for a UDA looks identical to the workflow designer, expect for the mention of User Defined Action in the top right hand corner.

 

UDA_designer.png

 

User Defined Actions Parameters

 

Just like regular actions in Nintex Workflow, UDAs can have input and output parameters. Eg.  If you were to create a UDA that would add two numbers together, you would have 2 input parameters (the 2 numbers) and 1 output parameter (the result).

 

To add parameters to the UDA, open the UDA designer, and click on the drop down for UDA Settings and then Parameters.

UDA_parameters.png

 

We simply add out parameters here, and make sure we configure the types to be what we need (input/output). You then use these parameters as you would use variables in a workflow.

 

User Defined Action Promotion

 

When you first publish a UDA, it is considered a Team Site User Defined Action.  It will only be available in the workflows you design on this site. You can promote a UDA to a site from the Manage User Defined Action page. Promoting a UDA from a team site level to a site collection level or farm level is SharePoint permission dependent.

 

promote_uda.png

 

When you click the Promote button on the Ribbon, a confirmation window will popup and it will promote the UDA to a Site Collection scoped UDA.  This means that any workflow, in any site, in this site collection will be able to use this UDA.

site_collection_UDA.png

 

To promote the UDA to the Farm, click on Switch to Site Collection Level Settings on the Manage user defined actions page. You'll be able to once again promote this UDA to now be Farm scoped.  Now any workflow in your farm can use this UDA.

 

You'll now see this action in Central Administration > Nintex Workflow Management > Manage User Defined Actions.

UDA_ca.png

 

Note: There is no Modify button for Farm scoped UDAs. In order to make any changes, you'd need to export, import, modify and promote again.

 

Importing and Exporting User Defined Actions

There are actually 2 ways to import/export a UDA.

1. Export the UDA as you would a Nintex Workflow

In the UDA designer, there is an Export button in the Ribbon. This will export the UDA to a .NWF file.

 

Although the exported UDA has a .nwf extension, it can not be imported into the regular Nintex Workflow designer page. It can only be imported in the User Defined Action designer page.  Therefore, if you download a .nwf action, you'll need to go to Manage User Defined Actions, click on Create and then Import on the User Defined Action designer.

 

2. On the Manage User Defined Action page

Select the UDA you want to export and click on Export in the Ribbon. This will export the UDA (action) itself, as a file with a .UDA extension.


To import the .UDA file, click on the Import button on the Manage User Defined Actions page.

 

What's the difference between the two export methods?

If you have a workflow (WorkflowA) which uses a user defined action, the UDA is linked to the action itself and not the design.  If you import the .UDA file and publish it, then import WorkflowA that uses it, it will automatically recognize that the UDA is there and you simply publish the workflow.

However, if you import the .NWF user defined action and publish it, when you import the WorkflowA, it won't see the UDA because the published version now has a different internal ID.

 

When moving UDA and Workflows between environments, I'd recommend exporting the UDA from the Manage User Defined Action page. This will preserve the connectivity between workflow and UDA.

 

Effects on a workflow

Using a UDA will increase the overall size of the workflow at runtime.  The size of the workflow can affect the starting of the workflow, especially the first time after an app pool recycle. However, the logic in the UDA would have been something you added to the workflow anyway. But by using a UDA, if you need to make changes or improvements, you change it in one place and have it automatically republish each workflow that uses the UDA. A much more efficient way to update all your workflows.

Outcomes