Control Forms

Introduction

What Are Control Forms?

Control Forms offer the possibility to collect data, before a certain action is executed. Just like ACFs (Activity Control Forms, see section Tab Activity Form Data) for workflow activities, Control Forms collect data for actions of the ConSol CM Action Framework, i.e., for the following action types:

The Control Form is opened and has to be filled in, before the action, i.e., the action script, is executed. Please read section Scripts for the Action Framework for a detailed introduction to scripts for actions of the Action Framework.

Like ACFs, Control Forms can be fine-tuned using scripts. Each Control Form can have the following scripts. They are both optional - a Control Form can also work perfectly without them.

Use cases like the following can be covered using Control Forms: 

When a Control Form has been displayed and the respective data have been filled in or modified, the action script which implements the ticket/customer/resource action is executed. Specific methods are available which deal with the Control Form data. This is explained in detail in section Working With the Data of Control Forms.

See the following example to get an impression how Control Forms work.

First Impression of Control Forms - a Control Form of a Resource Action

The resource page of a HP printer is open and the engineer executes the resource activity Create maintenance ticket for HP printer. A form is opened where the deadline and priority for the new ticket have to be entered. Only when the engineer has clicked Save and continue, the form data is saved and the resource action is executed. In the current example, it would not have been possible to enter nothing, since the form contains mandatory fields (marked by a red asterisk).

Figure 376: ConSol CM Web Client - Control Form of a resource activity

Defining Control Forms Using the Admin Tool

All components of Control Forms are defined in the Admin Tool.

A Control Form comprises at least one and can comprise three components: 

The Control Form Itself, Mandatory

It depends on the type of action to which the form should be assigned where in the Admin Tool you have to define the Control Form: 

In the following example , we will explain a customer/unit action. The principle applies to all Control Forms.

Perform the following steps: 

Define the Data Fields for the New Control Form

In order to create a new Control form for a customer action, open the navigation group Customers, navigation item Actions, Tab Control Forms. Click Add and select the data fields which should be part of the new Control Form in the Available section and move them to the Assigned section.

Please note that, unlike in an ACF for tickets where only ticket fields are available, in a Control Form, all types of data fields are available: 

  • ticket fields
  • customer fields: 

    • company fields

    • contact fields

  • resource fields

This implies that a Control Form can comprise data other than the data which belongs to the object of the action! For example: in a contact action, not only data of this contact, like email or phone, can be requested, but also every other data field like data of the ticket or of the company. Two things are of major importance here: 

  1. The action script decides what happens to the data of the form! So the developer of this script is responsible for the data processing!
  2. The behavior of the action script concerning auto-binding is crucial! See section Auto-binding about this! 

In the drop-down menus which work as filters above the list of data fields, you can select which type of fields you want to have displayed:

In the second drop-down menu/filter, you can select the data field group of which the fields should be displayed in the Available list. If you have selected a certain field type in the first drop-down menu/filter, only the matching field groups are displayed, e.g., only fields of the customer field group ResellerCompanyData (in our example).

Figure 377: ConSol CM Admin Tool - Customers, Actions: Creating a new Control Form for a customer action

In the example, some company fields of the customer field group ResellerCompanyData have been selected.

Assign the Control Form to the Action Where It Should Be Opened

When the new Control Form has been defined, you have to assign the form to an action of the Action Framework. In our example, to a company action.

Figure 378: ConSol CM Admin Tool - Customers, Actions: Assigning a new Control Form to a company action

Test the New Control Form

Open a company page in the customer group where the manual action has been assigned and execute the company action. The Control Form is opened and can be modified.

In the current example, the fields are already filled in, because the company fields have been filled already and the data is simply displayed. It could be modified within the form.

Please note the different behavior of the system concerning the saving of the form data depending on the auto-binding settings! See section Auto-binding about this!

Figure 379: ConSol CM Web Client - Control Form of a company action

Form Condition Script, Optional

In the Web Client, a Control Form is only displayed if

OR

The form condition script is stored in the Admin Tool, in the scripts section and has to be of type Control Form Condition. It has to return either true or false. In order to implement a form condition script, perform the following steps: 

  1. Write the Control Form condition script.
  2. Assign the script to the action as Form Condition Script.

Figure 380: ConSol CM Admin Tool - Customers, Actions: Assigning a condition script to a Control Form of a company action

If the script returns true, the Control Form is displayed, if it returns false, the Control Form is not displayed, but the action is executed.

The following example shows a Control Form condition script which checks if there are empty fields in the resource. Only then the form is displayed in order to gather the missing data. If all fields are already filled, no form is displayed.

if(resource.get("product.quantity") == null || resource.get("product.price") == null) {

return true

}

return false

Code example 68: Control Form condition script which checks if fields are filled

Form Prefill Script, Optional

If a form should be opened with some fields already filled in with specific values, you have to assign a form prefill script to the respective customer/ticket/resource action. In the script the fields can be filled.

For example, the following Control Form prefill script could be used to make sure the value for service status is set to a current value by an engineer.

company.set("ResellerCompanyData.service_status","unknown")

In the Web Client, the respective field is pre-filled with the given value: 

Figure 381: ConSol CM Web Client - Customer action and Control Form where one field has been pre-filled by a script

Please note the different behavior of the system concerning the saving of the form data depending on the auto-binding settings! See section Auto-binding about this!

When the form is opened: 

When the form is saved: 

The values which are set within a form prefill script are only used to fill out the form. The data is not persisted. If the data is really saved in the objects, depends on the action script, namely on