Part 3: Forms

1. In the category browser, right-click the Forms category and select New Form. On the forms home screen, click Next (if the home screen is opened first).
2. On the General settings screen, name the form
   Sales Orders Form
   then click Next.
3. Drag the Sales Orders Header view onto the form canvas.
Forms can have multiple views, along with additional controls not contained within a view. A single view can be added to multiple forms. For example, you might have a view that contains employee details such as name, department, email, address, etc. It makes sense to have the same look/feel/information on all of your forms, so to accomplish this, simply create one view and use it across your applications.



4. Rename the (Enter View Title) to
   Customer and Invoice Details



Your form theme may not be the same as the images in this tutorial. Some versions of K2 blackpearl may display the Lithium theme by default. The functionality is the same however.



5. Drag the Sales Orders Items view below the Header view. Rename the (Enter View Title) to
   Item Details

Your screen should look similar to the image below. (Your view formatting may be slightly different if you created your own styles. The form theme may be different depending on your K2 version.)



Next you will add a rule that will populate the Customer and Invoice Details: Sub Total field, with the Item Details: Items Total value. Recall in a previous step, you added the sum option to the Row Total column in the Items view and called it Items Total. The control name however, is Sum Data Label and you will see that value referred to in the next several steps. Just remember that Items Total and Sum Data Label refer to the same label/data label on the Items view.

Because you are working with two different views, you must add the rule to the form. You can add rules at the view level (as you did in the previous section), but the rule would only be able to interact with the view it was added to. To add rules that involve more than one view, or interactions between views, you must add the rule at the form level.
6. Click the Rules button located in the breadcrumb bar. Click Add Rule. Double-click the (Enter Rule Name) title and change it to
   Update Sub Total



7. Confirm the Events tab is highlighted and click the When a control on a View raises an event option found under the View Method heading. Notice that the event has been added to the rule definition pane.



8. Click the select View link and select the Sales Orders Items view.
9. Click the select control link and select the Sum Data Label control. Notice that K2 has automatically configured the event as when the control is changed.
Comments are a great way of documenting notes when adding rules. Comments help you remember why a configuration was made and they help others who may be updating your work understand your intentions.
10. Add a Comment to this event and enter the following (or if you prefer, your own content):
    This rule updates the Sub Total field on the Customer and Invoice Details view whenever the Sum Data Label changes on the Item Details view.

After adding the comment, notice the comment icon that appears to the right of the event line.



In the next step, you will configure the action for updating the Sub Total field in the Header view whenever the Sum Data Label changes in the I items view.

11. Click the Actions tab then search for the data transfer action using the keyword
    transfer
    then click on Transfer data to add it to the rule definition pane.



12. Click the (configure) link. In the context browser, expand Sales Orders Items > Controls > Footer Row(s).

Recall in creating the Sales Orders Items view, when you added the sum option to the Row Total column, K2 created a new row below the list and added the Sum Label and Sum Data Label into the bottom row. K2 calls this the footer row and that’s where you’ll find the Sum Data Label control.

Drag the Sum Data Label control into the Sub Total Text Box field, under the Sales Orders Header view. Click OK twice to complete the rule configuration.



In the next few steps, you will add a submit button and configure a rule to create new records in the Sales Orders Header and Items SmartObjects. Remember, the Header record will be the parent record, while the Items records will be the child records. There may be several child records for each single parent record; one child record per item ordered. The parent and child records will be bound to one another by an ID value.

13. Click the Layout button located in the breadcrumb bar (if it isn’t highlighted). Click the Controls tab in the context browser and drag a Button control to just below the Item Details view.



14. Click the button control to highlight it. In the Properties pane, change the Name to
    Submit Button
    and change the Text to
    Create Sales Order



Next you’ll add a rule to the Create Sales Order button to create the Sales Orders Header SmartObject record. This record is the parent record. It is a single record containing the Header view content.

15. With the Create Sales Order button still highlighted, click the control’s Rules tab at the bottom of the Properties pane. Click Add.



16. Confirm the Events tab is highlighted, then navigate to and click the event, When a control on the Form raises an event to add it to the rule definition pane. Notice that K2 automatically configured the event for when the submit button is clicked. (This is because you had the button highlighted. You could still add the event without the button highlighted and configure the button control properties if you needed to.)



Now, you will add a form field validation that requires three fields on the form before the form can be submitted.

17. Click the Conditions tab then search for
    validation
    and select the condition the Form passes validation to add it to the rule definition pane. Click the (configure) link and require the Region Drop-Down list, Sales Person Picker and Customer Drop-Down List.



And now, if the form passes the field validation, the first (parent) record can be created.

18. Click the Actions tab. Click the Execute a View method action to add it to the rule definition pane. Click the select View link and select Sales Orders Header. Click the select SmartObject link and select the Sales Orders Header SmartObject. Select Create for the method.



19. Click the (configure) link. On the Input Mappings screen, click Auto-Map. In this step, you are telling K2 to create the SmartObject record using the control values from the Header view.
Depending on the K2 version you are using for this tutorial, the ID Input Property may or may not be populated. If the ID property is not populated, it is safe to continue to the next tutorial step. At runtime, the record is assigned a unique ID when it is created. The ID is assigned by the data source itself. For instance, it may be a list ID in SharePoint, or a record ID in a SQL table. Since the ID is assigned by the data source, technically you do not need to map this property.



20. Click the Output Mappings button at the top of the screen. Drag the Return Properties > ID into the Sales Orders Header SmartObject > ID field. Click Finish to close the configuration screen, but stay on the actions screen in the rule designer.

In this step, you are saving the ID of the new record (think SQL record ID since the SmartBox is a SQL table) as the Header SmartObject > ID. This ID will be used as the HeaderID value in the Items records. This is the common value between the parent (Header) record and its child (Items) records.



Now that you have created a single parent record containing the Sales Orders Header content, you will create individual child records from each of the items ordered. (Each item ordered will have its own record.) These records will be created in the Sales Orders Items SmartObject.

21. Still on the Actions screen, click the Execute a View method for items that are in a specific state action to add it to the rule definition pane. Click the select View link and select Sales Orders Items. Click the select method link and select Create. Click the select item state and select Added.

This is the action you use to perform a looping type save. K2 will loop through each of the items and create a separate record for each.



22. Click the (configure) link. On the Input Mappings screen, do not auto-map this time. Expand the Context Browser and drag the Sales Orders Items SmartObjects properties into their corresponding fields (EXCEPT for the HeaderID property).



23. Expand the Sales Orders Header SmartObject and drag the ID into the Input Mappings HeaderID field. This is the ID you just saved in the previous step. The parent and child records are now bound by this ID. Finish the rule.



You will make one last adjustment to your create SmartObject actions. By default, the two actions are set to run one after another. You want them to run simultaneously so that each parent and child record is created together before K2 moves on to the next record or action. To do this, you must change the order to run as a batch.

24. Click on the link "then complete the following one after another" and change it to then complete the following in a batch.



Your rule definition pane should look like the image below. Finish the rule design to save it. Click OK to complete the Rule Designer, then Finish the form to save it and exit.

STEP 10 REVIEW

In this step you created the application’s form, or main container for all of the user interface elements. Your form contains two views, the Header view and the Items view, along with a submit button control. After adding the views, you configured a number of rules to transfer data from the I tems view (Items Total or Sum Data Label) to the Header view (Sub Total), then called the create methods for the Header SmartObject and the Items SmartObject. The Header content will become the parent record and the Items content will become the child records. You bound the two together by passing the ID field from the Header view to the HeaderID in the Items view. You need the parent and child records to be bound so that when you retrieve the records for the manager approval step, all associated records will be returned. Another important concept to remember is batch processing when the create record methods execute. This ensures the SmartObject records will be created at the same time, which is the faster and more efficient processing for parent/child records.

1. Right-click the Sales Orders Header SmartObject and select Design View. Click Next on the view home screen (if it opens by default).
2. On the General settings screen, name the view
   Customer Order History
   then change the category to the Views category. Select List View for the view type and UNCHECK the box to Call this method when the form loads. Click Next to continue.
Call this method when the form loads. Because you have designed this list view based off of a SmartObject, K2 by default will retrieve all content from the SmartObject when the view is loaded. You don't want this view to load content when the form is loaded. Rather, you will configure a rule that loads the content after a customer has been selected. The content is specific to the customer.



3. On the Layout screen, click Create Labels and Controls. Check the corresponding boxes to include the Order Date, Ship Date, Purchase Order Number and Total Due fields. Do not enable list editing or allow the user to manually refresh the list. Click OK, then Finish to complete the view. Check In the Customer Order History view.

As the view content will be read-only, there is no need for the user to make any edits.



4. Check out and edit the Sales Orders Form (if you checked it in the previous step). On the Layout screen, click the option arrow to the far right of the view menu and select Add Tab.



5. Double-click (Enter Tab Title) and change it to
   Sales Order Entry

This tab will now be for the primary view. The second tab will be for the order history view.



6. Click the New Tab icon, then change (Enter Tab Title) to
   Customer History



7. Drag the Customer Order History view onto the form design canvas. Change (Enter View Title) to
   Order History



Now that you have added the Customer Order History view to the Customer History tab, you need to add a rule that will call the Get List method for the Sales Orders Header SmartObject when a customer is selected. This will populate the Customer Order History view with the records from the current customer.

8. Click the Rules button located in the breadcrumb bar, then click Add Rule.
9. When the rule designer opens, confirm the Events tab is selected. Click the When a control on a View raises an event option found under View Method heading to add it to the rule definition pane. Change the rule name to
   Update Customer History List



10. Click the select View link and select Sales Orders Header. Click the select Control link and select Customer drop-down list. Click the select event link and select Changed.

In this step, you have added an event that will trigger whenever the customer drop-down list is changed.



Now you want to add a condition so that the a Action won’t fire off unless there is an actual value in the customer drop-down list. This will prevent unnecessary calls to the server if there wasn't a customer selected.

11. Click the Conditions tab. Under the Simple Comparisons heading, click on a control on a View contains a value to add it to the rule definition pane. Click the select View link and select Sales Orders Header, then click the select control link and select Customer Drop-Down List.



You have configured your event (the customer drop-down list is changed) and condition (the drop-down list contains a value), so now you are ready to configure the action, which is to call the Sales Orders Header > Get list method and populate the Customer History view.

12. Click on the Actions tab. Click on Execute a View method found under the SmartObject Interaction heading, to add it to the rule definition pane. Click the select View link and select Customer Order History. Click the select method link and select Get List.



13. Click the (configure) link. From the Input Mappings > Context Browser pane, expand the Sales Order Header view and drag the Customer Drop-Down List control into the Input Properties Customer field.

Here, you are simply assigning the customer drop-down list control as the control that will fire off your rule.



You do not need to configure Output Mappings for this rule, so click Finish, then OK to complete the rule configuration. Click Finish to complete the Customer Order History tab configuration. Check-in the form and all views.

STEP 11 REVIEW

Tabbed views can enhance the customer experience by providing additional information in a convenient and organized format. Tabbed content can include additional form fields and controls or informational content, as you built in this step. To maintain server performance, you included a condition that only makes the Get List call if a customer is actually selected.

1. Right-click the Customers SmartObject and select Design View. On the views home screen, click Next (if it opens by default).
2. Name the view
   Customer Details
   and change the category to the Views category. Confirm Item View is selected for the view type and click Next.
3. Click Create Labels and Controls. Change the number of columns to
   4
   and CHECK the Include AND Display Only boxes for the following fields: ContactPerson, Telephone, Email, DiscountRate, and Rating. Set the Label Position to Left with the Colon suffix. Leave the buttons methods boxes UNCHECKED. Click OK.

Since this pop-up will be for information only, you don't want any of the controls to be active. You can disable them quickly at the same time you select them.



In the next step, you will change the Rating Data Label from a number value to a Rating control. You will then disable it so that the control continues to be Display Only like the other controls shown above.

4. Click the Rating Data Label to highlight it. Change the control type to Rating. (A rating control looks like 5 stars that convey the rating number value to the number of stars that are highlighted.) With the rating control still highlighted, UNCHECK the Enabled box in the Properties pane found under the General heading. Click Finish to close the view designer. Check In the Customer Details view.



Now that you have created the Customer Details view, you will make it accessible from your Sales Orders Header view. You will add a button control that when clicked, will call the Customer Details sub-view.

5. Right-click and Check Out the Sales Orders Header view. Edit the view.
6. Click on the Controls tab in the Context Browser. Drag a button control into the cell directly above the Customer drop-down list. Name the control
   Customer Details Button
   and for the Text, enter
   Customer Details



7. With the Customer Details button still highlighted, click the control’s Rules tab. Click Add Rule.



Because you had the Customer Details button highlighted, K2 knew which event to apply to the control and automatically created the ‘When the control is Clicked’ event in the rule definition pane.

8. Click the Actions tab. Search for
   open a subview
   then click on Open a subview and execute a method to add it to the rule definition pane. (The image below reflects the action on the right side that should be added to the rule definition pane.)



9. Click the select View link and select the Customer Details view. Click the select method link and select List.

In this step, you are executing the list method, which behaves in the same manner as the get list method. It's retrieving the customer content from the Customers SmartObject to display in the Customer Details view.



10. Click the (configure) link. On the Subview Settings screen, expand the Context Browser > Sales Orders Header view node. Expand Controls > Customer Drop-Down List. Finally, expand the Customers SmartObject for that control. Drag the Customers.CustomerName into the Title Field. (Depending on your K2 version, the Customer SmartObject properties may be displayed without the SmartObject [table] object reference. For example, instead of Customers.CustomerName, you may just see CustomerName.)

For the Width enter
600px
and for the Height enter
300px

Here, you are formatting the size and the header for the sub-view pop-up the user will see. The header (in the image below, the header is the black bar that runs across the top of the image) will show the customer's name.



11. Click the Input Mappings button. Drag the Customer Drop-Down List control for the Sales Order Header into the CustomerId field. In this step, you are telling K2 that the customer selected from the drop-down list is the customer details you want to retrieve.



12. Click the Output Mappings button. Drag the corresponding Return Properties into the Customer Details Controls fields. Click Finish and then OK to complete the Customer Details button rule.

In this step, you are simply mapping the Customers SmartObject properties back to the Customer Details view fields. Output Mappings are what the user will see. In other words, when a customer is selected, K2 will fire off a rule that retrieves the selected customer's details and outputs them back to the Customer Details view.

When ready, click Finish to save and close the Sales Orders Header view.



You have now completed the Customer Details view and configured a button control to call the view as a sub-view that is populated with content from the Customers SmartObject. In the next few steps, you’ll test the sub-view and confirm it is functioning as intended.

13. Run the Sales Orders Header view.
14. First select a Region. Recall that the customer drop-down list is filtered according to the region selected, so you must select a region prior to selecting a customer. After you have selected a region, select a customer. Then click the Customer Details button.
15. Confirm the customer you selected shows up as the pop-up title and the customer details are present.



16. Click on the Sales Order Header view once again in the category browser to close the test view. Right-click and Check In the view.

STEP 12 REVIEW

Presenting additional information as an option to the user enhances the overall experience. In this step, you learned about another tool for providing additional form content to the user by means of a sub-view. By adding a button control and applying a rule that leverages the Customers SmartObject, you are able to increase the form’s functionality and increase content available to your user.

This concludes the forms configuration for the Sales Orders application. In Part 4: Workflows, you will create a basic one-step approval workflow that will start only if a form rule determines the total due value requires approval.