KB001723

Use Case

While required fields are great for fields that will always need to be filled out, sometimes you’ll want to require fields using logic instead. This will allow forms to be submitted without values until they are required. Custom submit logic creates a better user experience and can also control where the user ends up after they submit an entry. In this how to:

• Creating custom validation
• Configuring a message
• Stopping rule execution
• Closing the browser
• Navigating to another URL

This how-to uses the Item Review Accelerator as the starting point. To follow along, deploy the Accelerator and name it Incident Report. To find out more about using the Accelerators in your solution, use this link: http://help.k2.com/onlinehelp/k2appit/UserGuide/current/default.htm#App_Templates/App_Templates.htm

Creating the Incident Report Application

In the first part of this how-to, we will add fields to the Incident Report list and create a view to add in our forms. This technique easily adds information to the default accelerator and will prepare the process for the change to the submit logic.

1. Navigate to the List Settings of the Incident Report. Add the following columns all with their default settings:
   

   Date of Incident	Date and Time
   Incident Description	Multiple Lines of Text
   Incident Comments	Multiple Lines of Text
   Supervisor	Person or Group
   Name of Injured	Person or Group
   Incident Location	Single line of text

2. Navigate back to the Incident Report list, and in the ribbon select the K2 Application in the List tab. Wait for the application to finish validating the SmartObjects and select Regenerate SmartObjects.
3. Right click the Incident Review SmartObject and select Design View. 
   
4. In the General tab, name the View Incident Report Details with an Item View as the View Type and then select Next.
5. Select Create Layout Table Only, and create a table with 2 columns and 4 rows.
6. Drag the Supervisor field onto the View in the top left cell. This control will need to be changed to the picker type.
7. Select the field, and in the View Canvas ribbon, select Change Control and choose the type Picker, then select OK.
8. In the Properties of the Supervisor Picker, change the display field to Supervisor (Value). Under the Data Source settings for SmartObject, select the ellipses to configure the picker. 
   
9. Select the ellipses on the SmartObject to configure the data source. Expand the System folder and then the SharePoint 2013 Integration folder, and select the SharePoint Integration People Picker Source SmartObject and then select OK.
10. Next to the Method for Search, select the ellipses to configure the search options.
11. For SiteURL, use your site collection URL. For LabelName type AAD. For UserSelectionMode type PeopleOnly and for UserSelectionScope choose 0. Then select Finish.
    
     

    SiteURL	Friendly URL to your site collection
    LabelName	AAD
    UserSelectionMode	PeopleOnly
    UserSelectionScope	0

12. Uncheck All for the Filter Properties. Select Name, DisplayName and Email. Change the Identifier to ID and the Display to DisplayName. Then select OK.  
    
13. Drag the Name of Injured field onto the canvas and repeat steps 7-12 for the Name of Injured field.
14. Drag the Date of Incident and Incident Location fields onto the canvas on the second row. Merge the bottom 2 rows and drag the Incident Description and Incident Comments fields onto the canvas.
15. In the Controls menu, add a Data Label to the canvas. Name the Data Label Flag Data Label. This field will be used as a flag for conditional styles on the required fields. Uncheck the Visible option for the Flag Data Label in the Properties tab.
16. Select the Supervisor control. In the Properties menu select Conditional Styles and configure.
17. Name the condition Red – Supervisor and add a condition for when Supervisor Picker Is Empty And Flag Data label Is Not Empty then select OK. 
    
18. Set the Background color to light red and then select OK.
19. Repeat steps 16-18 for any required fields, switching the first condition to the current field. In our Submit logic, we will use the flag if there are values not set.
20. Select Finish to save and exit. 
    
21. Check Out the New Item Review View and select Edit. The buttons will need to be hid in the view because new buttons will be configured in the New Item Review Form for the submit logic.
22. Select the Save button and uncheck the Visible option.
23. Select the Cancel button and uncheck the Visible option.
24. Select Finish to save and navigate back to the Application elements page.
25. Check Out the New Item Review Form and select Edit.
26. Drag the Incident Report Details View onto the canvas between the New Item Review View and the Attachments View.
27. Uncheck the Collapsible option in the Properties of the Incident Report Details View.
28. From the Controls menu, add a 3 column 1 row Table under the Incident Report Details View.
29. From the Controls menu, drag 2 buttons into the table in the middle and far right cells. Name the center button, Button Submit with the text Submit and the far right Button Cancel with the text Cancel. Align the cells to the right and use the Save icon to save your work. 
    

Creating the Custom Submit Logic – Create Item Event

Before logic is added to the Submit event, the Submit button should be configured with the create item even so that the information required is saved to the list.

1. Edit the Select the Submit button and in the Rules task pane click the Add button to add a rule.
2. In the Events tab, add an event for When a control on the Form raises an event. In the options, select the Button Submit control.
3. Next in the Actions tab, add the Execute a SmartObject method Action to the rules.
4. Select the Incident Report SmartObject and the Create List Item method, then click configure.
   
5. Drag the Title Text Box onto the Title property from the Controls folder of the New Item Review View.
   
6. From the Incident Report Details View, expand the Controls folder and drag the controls onto the matching properties and then click Next. 
   
7. Under the New Item Review View, expand the Incident Report SmartObect. Drag the ID and Link to Item onto the correct properties and then click Finish. 
   

Creating the Custom Submit Logic – Validation

In your forms, there is often a requirement for information to be filled out, but it may not all be required at once, or you may want to create a notification to let the user know when they’ve missed something and provide information about what is required, and prevent any other rules from auctioning until the form is valid.

In this scenario, we will put together a series of conditions and actions in our submit rule to evaluate completed fields, rather than creating additional conditions to prevent the item from being submitted. If it is not complete, we will show a message and stop the actions that follow from firing.

1. In the New Item Review Form, select the Submit button in the View. From the Rules task pane, select the When Button Submit is Clicked rule and then click Edit.
2. Select the When Button Submit is clicked Event, and search for Advanced in the Conditions tab. Add the an advanced condition is true condition to the rules and move up to the top so that the Create List Item Action is removed from the condition. Rules execute in top down order, so the rules we want to evaluate first must come before the create action. 
   
3. Click on an advanced condition to configure the condition.
4. In the Conditions pane, add a condition. All conditions will use a field from the Controls folder, with the Is Empty Operator. For multiple conditions, change the And to Or in the Expressions so that if any field is empty, the condition will apply. Here is an example:
   
5. Select the condition, and in the Actions tab, search for View control and add an action to Set a View Control’s properties.
6. Select the Incident Report Details View and the Flag Data Label control. Then click configure.
7. In the Text property, type flag. Then select OK. This will be used to evaluate fields that should highlight.
8. Next search for message in the Actions tab, and add an action to Show a message. Then click configure.
9. For the Message Size choose Medium, and for the Message Type choose Warning. For the Title type Missing Entries and leave the heading blank.
10. For the body type Missing entries found in the Incident Report. Please review the entry for the following incomplete fields: followed by a list of the fields required by the logic. 
    
11. Search for stop in the Actions pane. Add an action to stop rule execution and then select OK to save changes and then use the save icon to save your work. 
    

Closing the Browser Window

For most cases you will want to have an action that lets the user know the actions have completed. In this first step, we will close the browser window of the active session.

1. Select the Submit button and in the Rules task pane, edit the When Button Submit is Clicked rule.
2. In the Actions tab, search for close.
3. Add the Close the browser window action to the end of your rules. Make sure that the close action is the last action in your rules. Any actions that follow a close event will not persist after the window closes. 
   
4. Click OK and then the save icon to save your work.

Redirecting the User to a URL

Sometimes it may be better to redirect the user. In this step, we will add a URL to redirect the user to the homepage of the site collection.

1. Select the Cancel button and in the Rules task pane, select the Add button.
2. Add an Event for When a control on the Form raises an event. Select the Button Cancel control.
3. Next in the Actions search for navigate and add an action to Navigate to a URL, then click configure.
4. Add the URL to the page you wish to redirect the user to. In this case, I am using the home page of the webinars sub site. Then click OK and then Finish to close the designer.
   

Loading the Details View into the Edit Form

1. Check out the Edit Item Review View and select Edit.
2. In the Layout tab, uncheck the Visible option for the Save and Cancel buttons.
3. Select Finish to save your changes and then check the View back in.
4. Check out the Edit Item Review Form and then select Edit.
5. Add the Incident Report Details View to the Form and uncheck the Collapsible option.
6. Navigate to the Rules tab, and select the When the Form is Initializing rule and select Edit Rule.
   
7. Search for transfer and add an action to Transfer data and click configure.
8. From the Context Browser, expand the Incident Report SmartObject in the Edit Item Review View, and drag the fields onto the controls of the Incident Report Detail View and select OK.
   
9. For any picker controls, search for view control and add an action to Execute a view control method for each picker.
10. Select the Incident Report Detail View and the Name of Injured picker with the Resolve method and then click configure.
11. From the Context Browser drag the Name of Injured (Value) onto the Value field from the Incident Report SmartObject in the Edit Item Review View, then select Finish.
12. Repeat steps 9-10 for the Supervisor Picker.