How To: Using Form States

This article illustrates how to use form states. States allow you to use the same form for different workflow tasks. One form can have many states. Each state has its own set of rules that you can edit depending on the scope of the task. In this demonstration, you create a workflow with two tasks. You customize the state's rules for each task so that the form behaves differently based on the task scope and recipient. For more information on states, see Form States.

Three state configurations of the same form
Form States

When to Use Form States

Use states when you want to use the same form for different tasks in a workflow. States are part of a form's rule configuration and allow you to customize the rules based on a workflow task. Each task has a state associated with it. You can use the same state for multiple tasks or you can create a new state for each task. For example, you have a state for the originator's task when they first submit the form. You might hide controls or views the originator does not need to see, such as controls or views that only the approving manager uses. Likewise, you might hide controls the approving manager does not need to see, such as create or delete buttons. You can use the same form for tasks in a single workflow and even across multiple workflows.

Scenario

You work in IT and have automated several of your organization's business processes. Most processes contain a workflow that includes one or more approval tasks. Each process has one form which you customize based on the workflow task at hand. Using states, you can add and edit rules based on each workflow task.

Steps

In this demonstration, you create a SmartBox SmartObject along with a view and form. You create a workflow containing two task steps. You create a new state for each task. After deploying the workflow, you edit the form and customize the state rules for each workflow task.

Setup Steps

The following steps set up the scenario from start to finish. If you want to skip the setup steps and view the topic step, go to Edit Form Rules.

  1. In K2 Designer, create a SmartBox SmartObject called State Sample with the following properties: Name (Text), Department (Text), First Task (Text), and Second Task (Text). (Optional) Create categories first to keep your work organized.
    1. Launch K2 Designer.
      If you do not know how to access K2 Designer, see Accessing Sites.
    2. Begin by creating categories to keep your work organized. Right-click All Items and select New Category. Use the image below as a sample for creating categories for this demonstration.
      Create Categories
    3. Next, create the SmartObject. Right-click the Form States category and select New SmartObject. Name the SmartObject
      State Sample
      and confirm the SmartBox option. Click Create.
      Create SmartObject
    4. Add the following properties:
      Name (Text)
      Department (Text)
      First Task (Text)
      Second Task (Text)
      and click Finish to save and exit the SmartObject.
      Add Properties
  2. Design an Item View from the State Sample SmartObject called State Item View. Add all the properties except ID. Add the Create standard button.
    1. Right-click the State Sample SmartObject and select Design View.
    2. Name the view
      State Item View
      and confirm the type is Item View. Click Create.
      Create Item View
    3. Click Create Labels and Controls.
      Create Labels and Controls
    4. Include all the fields except ID. Change the label position to left and enable the colon suffix. Add the Create standard button. Click OK.
      Add Fields and Buttons
    5. Your view should look like the image below. Click Finish to save and exit the view.
      Finish View
  3. Design a form from the item view called State Form.
    1. Next, you design a form from the item view. Right -click the State Item View and select Design Form.
    2. Name the form
      State Form
      and click Create.
      Create Form
    3. There are no other edits to the form at this time, so click Finish to save and exit. You return to the form after building the workflow to customize each state's rules.
  4. Add a workflow called State Workflow. Configure the Start step so that it uses the State Form and Create button to start the workflow. Change the default state name to Originator Submit State.
    1. Right-click the Form States category and select New Workflow.
    2. Name the workflow
      State Workflow
      and click Create.
      Create Workflow
    3. You see a Welcome screen with an interactive panel. You can click the right and left arrows to learn more about the workflow designer. Click Close to proceed to the design canvas.
      Welcome Screen

    4. You begin the workflow by configuring the Start step. Select the Start step and expand the Configuration Panel. (When selected, steps have a blue border.)
      The Configuration Panel allows you to configure and customize the steps you add to your workflow.
      Expand Configuration Panel
    5. Click Add a SmartForm start event.
      Add SmartForm Event
    6. Navigate to and select State Form. In the image below, the path is: How To > Form States > State Form. Your path may be different depending on your categories and naming convention. Click OK.
      Select Form
    7. The Start Workflow from a Form wizard launches.

    8. On the References screen, notice the workflow discovered the State Sample SmartObject. A reference is created to this data source that allows you to use its properties and methods throughout the workflow. There are no changes to this screen, so click Next.
      References
    9. On the Start Rule screen, select Help me configure it. This option steps you through each setting so you can customize your start settings. Click Next.
      Start Rule
    10. You are now on the Form State screen. The first state represents the form's behavior for the originator, or person who submits the form in the first place. Notice that the workflow automatically creates a new state and names it based on the workflow (State Workflow). Change this name so that it is more descriptive. Replace State Workflow with
      Originator Submit State
      and click Next.
      Form State
    11. On the How Does Your Form Start the Workflow screen, the default rule is On State Item View, when Create Button is Clicked. Since the Create Button is the only button, the workflow assumes this is the control you want to use to start the workflow. Click Next to continue.
      Form Rules
    12. On the summary screen, review the changes the workflow makes to the State Form rules. Click Save and Finish. When you see the success check, click OK.
      Summary
    13. Notice now that the start screen reflects the correct form and event that starts the workflow. Collapse the Configuration Panel by clicking the slider.
      Start Events
  5. Add a Task step followed by a Decision step. Use the table below as a guide for configuring the task step properties.
    Tab/
    Property
    ValueNotes
    Task/
    Instructions

    Select First Task Complete and click Submit.

    Enter instructions for the task recipient.
    Form/
    Form Type
    SmartForm 
    Form/
    Form
    State FormNavigate to and select State Form.
    Open Task on a Form (wizard)
    ReferencesNo change 
    Open TaskHelp me configure it 
    Workflow ViewCreate a new StateFirst Task Step State
    Open Task RuleNo change 
    After Submit ActionNo change 
    SummarySave and Finish 
    Task/
    Actions

    First Task Complete

    You need one action for testing. In the real world, you might have several actions such as Approved, Denied, and Rework.
    Recipients/
    Recipients
    OriginatorYou assign the task to yourself for testing.
    Properties/
    Name
    First Task StepThis is the name of the step you see on the design canvas and in reports.
    Add another Task step followed by a Decision step. Connect the task step to the First Task Complete outcome line. Use the table below as a guide for configuring the second task step properties.
    Tab
    Property
    ValueNotes
    Task/
    Instructions

    Select Second Task Complete and click Submit.

    Enter instructions for the task recipient.
    Form/
    Form Type
    SmartForm 
    Form/
    Form
    State FormNavigate to and select State Form.
    Open Task on a Form (wizard)
    ReferencesNo change 
    Open TaskHelp me configure it 
    Workflow ViewCreate a new StateSecond Task Step State
    Open Task RuleNo change 
    After Submit ActionNo change 
    SummarySave and Finish 
    Task/
    Actions

    Second Task Complete

    You need one action for testing. In the real world, you might have several actions such as Approved, Denied, and Rework.
    Recipients/
    Recipients
    OriginatorYou assign the task to yourself for testing.
    Properties/
    Name
    Second Task StepThis is the name of the step you see on the design canvas and in reports.
    1. From the Toolbox > Basic node, drag a Task step into the empty placeholder below the Start step.
      Add Task Step
    2. With the Task step highlighted, expand the Configuration Panel.
      When adding a step to the workflow design canvas, you may see a red warning badge. This badge simply indicates the step has required configurations. When you expand the Configuration Panel, the required configuration is also flagged.
    3. Confirm the Task tab is active. For the Instructions, enter
      Select First Task Complete and click Submit.
      For the Actions, click the Add(+) icon. Enter
      First Task Complete.
      Instructions and Actions
    4. Select the Form tab. Under the Form Type heading, select SmartForm. Under the Form heading, select State Form. (If State Form is not displayed, click Browse to navigate to the form.)
      Select Form
    5. The Open Task on a Form wizard launches.

    6. On the References screen there are no changes, so click Next.
    7. On the Open Task screen, select Help me configure it and click Next.
    8. You are on the Workflow View screen. Here, you can keep or change the state associated with this task. Keep the setting to create a new state, but change the name to
      First Task Step State
      and click Next.
      Create State
    9. There are no changes to the Open Task Rule Action screen, so click Next.
    10. There are no changes to the After Submit Action screen, so click Next.
    11. On the summary screen, review the changes the workflow makes to the form rules and click Save and Finish. When you see the success check, click OK.
    12. Select the Recipients tab. Keep the default value, Originator. This makes testing easier if the person submitting the form (you!) also takes action on the tasks.
      Task Recipient
    13. Select the Properties tab. Change the name of the step to
      First Task Step
      and collapse the Configuration Panel.
      Change Step Name
    14. From the Toolbox > Logic node, drag a Decision step below First Task Step. Connect the two steps.
      To return to the Toolbox main menu, click the Toolbox icon in the breadcrumb bar.
      Toolbox Icon
      To connect two steps, hover over the border of the first step until you see a handle. Drag the handle into the second step. Click on the design canvas to set the line.
      Connect Steps
      Task and Decision Steps
    15. From the Toolbox > Basic node, drag a second Task step onto the design canvas and align it with the First Task Complete outcome line. Connect the line to the step.
      Add Second Task Step
    16. Select the Task step and expand the Configuration Panel. Use the table below as a guide for configuring the second task step.
      Tab
      Property
      ValueNotes
      Task/
      Instructions

      Select Second Task Complete and click Submit.

      Enter instructions for the task recipient.
      Form/
      Form Type
      SmartForm 
      Form/
      Form
      State FormNavigate to and select State Form.
      Open Task on a Form (wizard)
      ReferencesNo change 
      Open TaskHelp me configure it 
      Workflow ViewCreate a new StateSecond Task Step State
      Open Task RuleNo change 
      After Submit ActionNo change 
      SummarySave and Finish 
      Task/
      Actions

      Second Task Complete

      You need one action for testing. In the real world, you might have several actions such as Approved, Denied, and Rework.
      Recipients/
      Recipients
      OriginatorYou assign the task to yourself for testing.
      Properties/
      Name
      Second Task StepThis is the name of the step you see on the design canvas and in reports.
    17. Add a Decision step and connect it to the Second Task Step.
      Add Decision Step
    18. For testing, you open the form for the first and second tasks and review the form content. You don't need the workflow to proceed any further for this demonstration. However, you cannot deploy the workflow if there is an orphaned outcome line. As a workaround, you connect the outcome line to a placeholder step that allows you to deploy the workflow for testing.

    19. From the Toolbox > Basic node, drag a Placeholder step onto the canvas and align it with the Decision step. Connect the Second Task Complete outcome line to the new step.
      Placeholder Step
  6. Deploy the workflow. Close the workflow designer and return to K2 Designer.
    1. Before you can use the workflow, you must deploy it. Deploying the workflow publishes it and makes it available for use. If you make any changes to the workflow, you must deploy it again so that the changes are updated on the server.Click File > Deploy. When you see the success dialog, click File > Close to return to K2 Designer.
      Deploy Workflow

Edit Form Rules

In the next step, you edit the form and customize the rules for each task state by hiding or showing controls.

  1. Edit the State Form. Edit the form initializing rules for the First Task Step State and Second Task Step State. Use the table below as a guide for hiding or showing controls.
    StateRuleEdit
    First Task Step StateForm Initializing1. Hide the Second Task label and text box.
    2. Hide the Create button.
    Second Task Step StateForm Initializing1. Hide the First Task label and text box.
    2. Hide the Create button.
    1. Right-click the State Form and select Edit.
    2. Click the Rules tab. The states created in the workflow appear on the left side of your screen. Click through the states and notice how each one has its own set of rules displayed on the right side of your screen. (The Base State acts as a starting point for rules. Any rule you edit in the base state filters down throughout the other states.)
      States and Rules
    3. The Originator Submit State is the form's behavior and configuration for the person who submits the form in the first place. This is the state that has a rule action that starts the workflow.

    4. Select the Originator Submit State, On State Item View, when Create Button is Clicked rule. Click Edit Rule.Rules consist of events, conditions and actions. A valid rule contains at least one action.
      Events define when the rule should run, such as when a button is clicked, or when the form loads. (Events are optional, you can define "event-less" rules that you can call from other rules.) Conditions define whether the rule should run. If the criteria are true, continue the rule, and if the criteria are not met, stop the rule. For example, a condition might evaluate a form to confirm that required fields have content. (Conditions are optional - not all rules will require conditions.) Actions define what the rule should do. For example, show a message, start a workflow, or enable a form field. Rules can contain multiple actions that are run in sequence or in parallel.
      Edit Rule
    5. You see the event and actions for this rule (it does not have any conditions). The event (Create Button is Clicked) has two actions: create the record in the SmartObject and start the workflow. Click Cancel and Yes to exit the rule designer.
      Rule Definitions
    6. Select the First Task Step State and the When the Form is Initializing rule. This state controls the form's behavior for the first task recipient. You will hide the second task label and text box controls, along with the create button. Click Edit Rule.
      First Task Step State
    7. You already have an event (When the form is Initializing) so next you add the action that hides the second task label. With the Actions tab selected, enter the keyword
      hide
      in the search text box. Click Hide a View control to add it to the rule definition pane.
      You can scroll through events, conditions, and actions or you can use the search text box to enter keywords. As you type, K2 resolves the keyword and returns your search results.
      Hide Control Action
    8. Click the select control link and select Second Task Label.
      Hide Control
    9. Repeat the steps above and add another instance of the Hide a View control action to the rule definition pane. This time, select the Second Task Text Box control.
      Hide View Controls
    10. Now you hide the create button since the task recipient does not need to add new records. Once again, click the Hide a View control action to add it to the rule definition pane. Select the Create Button control. Click OK to save the rule definition.
    11. Your form initializing rule should look like the image below.
      First Task Form Initializing Rule

      Next, you edit the Second Task Step State form initializing rule. You mirror the form initializing rule from the First Task Step State, only this time you hide the first task label and text box controls along with the create button.

    12. Edit the Second Task Step State, When the Form is Initializing rule.
      Edit Second Task Step State
    13. With the Actions tab active, search for
      hide
      then click Hide a View control three times to add three instances of the action to the rule definition pane.
      Hide a Control Action
    14. Edit each action so that the following controls are hidden: First Task Label, First Task Text Box, and Create Button. Click OK to save the rule definition.
      Completed Form Initializing Rule
    15. Click Finish to save and exit the form.
    16. Right-click the State Form and select Check In. When you see the warning pop-up, select the option to check in associated views. Click OK.
      Check In View and Form
  2. Launch the State Form using the Runtime URL. After submitting the form, launch Workspace and review how the form changes based on the task (first or second).
    1. To test your rule edits, begin by submitting the form. Select the State Form and click the Runtime URL link in the central pane.
      The Runtime URL is used to launch the form in a web browser. Use this URL as the public link to this form. For example, use this link in emails or web pages to provide access to other users.
      Runtime URL
    2. Complete the form fields and click Create. Remember, when you click the create button, the content is added to the State Sample SmartObject and the workflow is started. (After you click the create button, you will not have any other indication the form submitted. In the real world, you might clear the form fields upon submit or display a message confirming the action.) Close the browser window.
      Submit Form
    3. Launch Workspace.
      If you do not know how to access Workspace, see Accessing Sites.
    4. Click the Inbox to view the tasks assigned to you.
      Workspace Inbox
    5. Click the task notification for the First Task Step. The State Form opens on the right side of your screen. First, notice there are now two views: Workflow and the State Item View you created earlier. The Workflow view is automatically added and this view displays the instructions, actions, and submit button. Review the fields on the State Item View. Notice the second task label and text box, along with the create button are hidden. Select First Task Complete from the Select Action drop-down list and click Submit. Click OK when you see the confirmation message.
      State Form Workflow View
    6. Click the Refresh icon to update the task list. The Second Task Step notification appears. Click this notification and review the form fields. Notice the first task label and text box, along with the create button controls, are hidden. You do not need to action this task.
      Second Task Notification
Review

In this demonstration, you worked with states. A state represents the configuration and behavior of a form for a specific use. States are often associated with workflow tasks and a single form can have many states. Rather than creating multiple forms, you can use one form with different states, then apply rules to control form behavior for each of the states.