Datapolis Process System


Home > User Guide > Using Workflows > List Workflows > Custom Add Item List Form

Custom Add Item List Form

By design, list workflows always require an item to be created on the list before any workflow could take over handling its lifecycle. For instance, a Leave Request Processing workflow would require an item representing said leave request to first be added to the list using the standard Add Item form, and only with that prerequisite fulfilled the workflow could begin its work, resulting in the request's approval or rejection. Because of the fact that two different mechanisms needed to be used (one - standard SharePoint list form, the other - Datapolis Workflow), it was harder to manage which fields a user should be allowed to change. Since adding an item is not part of the workflow, field visibility has to be set by customizing either the Add New Item form or the item's Content Type, or by using external tool like Datapolis Column Protector. Also, any visual customization like company branding would potentially need to be applied in two places, making later maintenance and changes that much harder.

To streamline the process, Datapolis Process System lets you design a Workflow Initiation Form and display it to the user when creating a new list item. For instance, this is what users may see after clicking the "New Item" button:

Please note the Datapolis Procecss System-style header and footer, indicating the form's origin.

Letting Datapolis Process System to create a custom Add Item form is a straightforward procedure. First, you need to go to the Settings form in Datapolis Workflow Designer and in the "Workflow initialization method" section untick the "When new item is created" option. This will cause the "Via list's New Item Form" option to become active. Check the box next to it - and you're done. You can also supply a custom page name in the textbox below, if the one proposed by the Designer does not suit you.

The next step is to design the form itself. You can find extensive information on the process in the Workflow Initiation Form and Action Launch Forms chapters. The general idea is to create a set of workflow variables that will hold the data received from the user. Using leave request as an example, let's consider the following fields users will need to fill in when registering a new request: Leave Start, Leave End, Leave Type and Comment. Since these will be the fields in our form, we should prepare four workflow variables, as shown on the illustration below:

Make sure the first two (Leave Start and Leave End) are of the "Date time" type; the other two should stay as the default "String" type.

More about workflow variables can be found in the Variables chapter.

With that done, we can now define the fields in our form. Double click on the Workflow Initial State on the workflow diagram, then click the "Initiation Form" button in the right pane.

Note the "Variables" and "Fields" sections. The "Variables" section contains all the variables defined within our workflow - currently we have only the four defined before. The "Fields" section is empty, meaning our form does not have any fields at the moment. To add a new field, simply move the "Leave Start" variable from the "Variables" to the "Fields" section. You can use the "+" icon next to the variable, or simply double click it. Do this for all variables.

What is left to do, besides fiddling with the settings of each of the fields (which won't be covered here; you can find more information in the Action Launch Forms chapter) is to process the data received from the user. Note that while the form does automatically create new list item, it does not fill its fields with provided values as the standard SharePoint form does. Instead, the form saves field values to workflow variables which can the be used within the workflow and processed accordingly to business requirements. Since in this example we don't plan on processing the data in any way, we'll just go ahead and save it to the list.

Double click the Initial Action on the workflow diagram, then open the "Activities" window. Next, drag-and-drop the "Edit Items" activity onto the diagram.

Now set the activity parameters accordingly, passing our workflow variables to individual fields of the new list item.

That's everything in Datapolis Workflow Designer. Deploy the workflow and Datapolis Procecess System will create the new form for the list. Now exit the Datapolis Workflow Designer and go back to the Datapolis Process system Settings page for the list. In the "List Workflows" section you will see the "Initiation form" column next to your workflow. By default, the newly created form will not be set as the default Add Item form for the list, meaning that when a user clicks the "New Item" button, they will be presented with the standard SharePoint list form. By checking the checkbox in the "Initiation form" column, you will set our custom form as the default Add Item form for the list. You can at any timme unassign the form as the default and reassign it again as need be, without redeploying the workflow.

Important: There are several important things to note about setting up Workflow Initiation Form as the list's Add Item form. First of all, currently only generic lists are supported, while document libraries are not. Also, if a list has several content types, they will all share the same default list form, or, if they have their own forms defined, they will use them instead. Be also aware that only list workflows support this feature. Reusable workflows currently do not support custom Add Item forms.