Audience
  • Developers
  • Form Designers
Required Knowledge
  • SmartObjects
  • Views
  • Forms
  • K2 Workflow Designer in particular 'Map the Identity Field' (Create Item Reference)

Introduction

Important:
  • The Map the identity fields to the workflow option on the Workflow Name screen has been replaced by the option to create an Item Reference from a SmartObject. Data Fields are no longer automatically created for the identity field of the SmartObject. An Item Reference is now created using the default SmartObject linked to the Form.
  • The latest How To topics are available in the K2 Five User Guide or the K2 Cloud User Guide’s How to section.

An Item Reference is an XML structure that contains all the information of the specific SmartObject. The Item Reference feature automatically binds the SmartObject data used in a Form to the workflow making it easier and quicker to design a workflow. This eliminates the need to manually configure certain rules such as the rule to return data on a Form at approval and the need to define each Data Field. The Item Reference replaces the Identity Field/Data Field configuration as it has expanded upon the previous functionality.

  • If the SmartObject is bound to a List View or an Editable List View, the Item Reference will automatically bind to the default List method of that SmartObject.
  • If the SmartObject is bound to an Item View, the Item Reference will automatically bind to the first Load method found in that SmartObject.
  • If there is more than one View on the Form, the specific SmartObject to be used as the Item Reference must be manually selected from the Context Browser.

If the option Map the identity fields to the workflow was used in a build prior to K2 smartforms 1.0.2, it will still be functional. However, should there be a need to edit the workflow and use the Item Reference feature instead, it is advised that the following steps are taken to ensure that performance is not affected:

  • Manually remove all Data Fields that were previously automatically created as a result of the identity fields used in the workflow
  • Manually remove Data Bindings to these Data Fields in the workflow
  • Manually remove Rule Actions that were previously automatically added as a result of the identity fields used in the workflow
Important: There is a risk where incorrect Data Fields, Data Bindings or Rules/Rule Actions may be removed which will result in unexpected behavior. It is therefore advised to use Item References when configuring new workflows in K2 smartforms and keep the existing configuration for workflows configured prior to K2 smartforms 1.0.2.

Implementation Details

The Item Reference option is available on the Start Event and on the User Form screen of the SmartForms wizards.

Image
Image

Item Reference – Represents the SmartObject used to create the Item Reference. The default SmartObject that is bound to the Form is used by default. If the field is blank, there are more than one View linked to the Form and the specific SmartObject to be used to create the Item Reference should be selected from the Context Browser. To use another Item Reference for a specific event, click on the ellipsis next to the Item Reference and select the required View and reference.

Image

Example Scenario

In the scenario below we are using a Form with two Views. We will have to select the SmartObject to create an Item Reference as there are more than one View on the Form. Follow the steps below to set up the scenario:

  1. Create two SmartObjects as shown below:
    Image
    Image
  2. Create an association between the two SmartObjects.
  3. Create an Item View, List View and Form of the Customer SmartObject and an Item View and List View of the Region SmartObject.
  4. Add a Tab for the Region information on the Customer Form then add the Region Item View and Region List View to this Tab. 
  5. Create a workflow using the Customer Form.
  6. Since there is more than one View on the Form, the Item Reference is not automatically populated and we have to select the SmartObject from the View to be used. Drag the Customer SmartObject from the Context Browser as shown below.
    Image
  7. Continue with the workflow.
  8. The workflow will start when the Create Button is clicked on the Customer Item View as shown below:
    Image
  9. Supply relevant information in the rest of the wizard, then complete the wizard.
  10. Drag a User Task onto the canvas.
  11. Type Manager in the Name field.
    Image
  12. Continue with the wizard until the User Form screen. The Item Reference is automatically populated.
    Image
  13. Click Next.
  14. The Manager Activity worklist item will be opened when the Form is initializing as shown below. Move the "then open the Manager Activity worklist item" down as shown below (this will ensure the data is returned first in the Form)
    Image
  15. Complete the wizard.
  16. Drag a Placeholder event onto the Complete Outcome.
  17. Save and deploy the workflow.
  18. Create Region information by completing the Region Item View.
  19. Run the Customer Form. Complete the information on the Customer Item View on the Form and click Create.
    Image
  20. The workflow is started and the Manager worklist item is created.
  21. Open the worklist item. Note how the details are loaded on the Form without us having to create any Rules.
    Image