Self Help - Forms
A form is a type of resource in a Self Help project. It is used to collect information entered by users when running a procedure.
- Forms are built and managed in edit mode in Desktop Studio.
- You can define the structure in the Conception pane.
- You can define the properties in the Description pane.
- They can be inserted in the procedure of a Self Help project.
See the use case.
- The information collected is stored in project variables that can be used in automatic or manual actions during the procedure.
- They can be dynamic.
See the description.
Structure of a form
- A form is made up of cells, each of which can contain an element, e.g. text field, list of values, etc.
See Types of elements in forms.
- The properties of each element can be modified to define the form's visual aspect and behavior on screen.
Example
- Define a form to collect the information required for creating a ticket in Service Manager
See the use case for the Service Manager connection package.
- Define a form to collect the information required for sending an email via a connector
- Define a dynamic form for displaying the different logos of EasyVista products on a given page depending on the user's options
See the use case.
Caution
- When you reduce the number of rows or columns in a form, all of the rows or columns that exceed the number you specify will be deleted.
example Form with four rows reduced to three rows ==> The last row of the form will be deleted.
- You cannot modify an element's type once you have inserted it in a form. You must delete it and then create it again.
Best Practice
- Use dynamic forms as an alternative to a tree structure with several branches.
- Create groups of fields to structure your form.
- Use labels to add titles to different sections in a complex form.
- Copy and paste to move different form elements.
- You can initialize the items in a list of values in different ways.
See Input/Output tab > Advanced Mode.
- If the values in the list are only used in the form, you can use parameters to enter them. Their display is restricted to the objects using them and those calling them. This is the default option.
- If you want to reuse the values in the list in other forms within the same Self Help project, you should enter them using variables in the project library. They will then be visible and common to all objects in the Self Help project.
Characteristics of forms
Dynamic forms
See the use case.
- Dynamic forms contain one or more dynamic fields.
See the properties of the Type and Validation tab in the Description pane.
- A computing procedure, transparent to users, is associated with the dynamic form. It is used to run a script found in the macro of an Action step.
Note: The computing procedure is unique, regardless of the number of dynamic fields in the form. It must therefore take into account all of the criteria in the form page. - When a dynamic field value is modified, the computing procedure is run and the page will be refreshed using the new criteria.
Types of elements in forms
Element | Description | Display | |
---|---|---|---|
Input field | Displays a label followed by a field for entering text in a single row. | ![]() |
|
Password field | Displays a secure field for entering a password.
The characters entered are automatically hidden by the tilde, *. |
![]() |
|
Group of fields | Used to group several elements together in a cell. | ![]() |
|
Label | Displays text in read-only mode without an input field.
example Add titles to separate sections |
![]() |
|
Multiple choice list of values | Displays a list from which users can select multiple values.
Several display modes are available, e.g. action buttons, checkboxes, lists, etc. |
![]() |
|
Single choice list of values | Displays a list from which users can select only one value.
Several display modes are available, e.g. action buttons, checkboxes, lists, etc. |
![]() |
|
Multiple lines input field | Displays a field for entering text in multiple rows. | ![]() |
Display modes for lists of values
Multiple choice list of values and Single choice list of values elements
See How to specify a list of values.
Display mode | Description | Display | |
---|---|---|---|
Buttons | Values appear as action buttons.
They can be displayed all in one row or one below the other. Users can select several values. |
![]() |
|
Radio buttons | Note: Only for single choice lists of values.
A radio button appears next to each value. They can be displayed all in one row or one below the other. Users can select only one value. |
![]() |
|
Checkboxes | Note: Only for multiple choice lists of values.
A checkbox will be placed next to each value. They can be displayed all in one row or one below the other. Users can select several values. |
![]() |
|
Lists | Values are displayed in a list.
Users can select several values. |
![]() |
|
Drop-down list | Note: Only for single choice lists of values.
Values are displayed in a drop-down list. Users can select only one value. |
![]() |
Screens description
(1) Explorer pane: Displays the project variables and elements in the form.
(2) Conception pane: Workspace for designing the form, with a toolbar at the top of the pane. See How to create a form.
(3) Description pane: Pane specific to the element selected in the Conception pane, used to define its contents and layout.
Toolbar
List of functionalities
- Used to toggle between read-only mode and edit mode.
- Used to save the form.
- Used to add a form element only in an empty cell.
See the detailed procedure.
- Used to add a row or column.
- Used to delete a row or column.
- Used to show or hide the grid around cells.
- Used to undo or redo the last modification.
- Used to change the writing language.
Description pane
The Description pane is specific to the element selected in the Conception pane.
Global form properties
Used to define the structure of the form:
- Number of rows and columns in the form.
- Space between each cell. By default, 5 px.
Access: Click outside the form in the Conception pane.
Label properties tab
Note: Only for Label elements
Tooltip: Text found below the form element, displayed to users.
Layout: Layout options for the form element.
- Row span / Column span: Used to merge the cell containing the element with empty adjacent cells.
- To merge empty adjacent rows, specify the Row span field.
- To merge empty adjacent columns, specify the Column span field.
example Row span = 2
- Position: Position of the element, i.e. label and input field if applicable, within the cell. Move the cursor over
to see possible positions.
- Horizontal fill: Used to indicate if the element's width should be adjusted to occupy the entire width of the cell (box is checked) or if its original width should be kept (box is not checked).
- Vertical fill: Used to indicate if the element's height should be adjusted to occupy the entire height of the cell (box is checked) or if its original height should be kept (box is not checked).
Display tab
Used to configure the display of the form element selected in the Conception pane.
Title bar: Label of the form element, displayed to users.
- The icon next to the title shows the type of element.
- Translate the label into different languages by selecting the language you want from the drop-down list at the right of the toolbar.
Tooltip: Text found below the form element, displayed to users.
Layout: Layout options for the form element.
- Row span / Column span: Used to merge the cell containing the element with empty adjacent cells.
- To merge empty adjacent rows, specify the Row span field.
- To merge empty adjacent columns, specify the Column span field.
example Row span = 2
- Position: Position of the element, i.e. label and input field if applicable, within the cell. Move the cursor over
to see possible positions.
- Horizontal fill: Used to indicate if the element's width should be adjusted to occupy the entire width of the cell (box is checked) or if its original width should be kept (box is not checked).
- Vertical fill: Used to indicate if the element's height should be adjusted to occupy the entire height of the cell (box is checked) or if its original height should be kept (box is not checked).
Selector appearance (Note: Only for Multiple choice list of values and Single choice list of values elements): Display modes available for the list, e.g. action buttons, checkboxes, lists, etc. See Display modes for lists of values.
- Only for buttons, radio buttons and checkboxes: Select the Horizontal box to display all values in a single row.
Label (Note: Except for Label elements): Layout options for the form element's label field.
- Width:
- Automatic: The width of the label field will automatically be adjusted to the size of the label.
- Specific: Specify the desired display width in pixels.
- Left and On top: Used to indicate if the label field should be positioned to the left or over the element's input field.
- Position: Position of the label within the label field. Move the cursor over
to see possible positions.
Input field (Note: Except for Label elements): Layout options for the form element's input field.
- Width (Note: Only if the Horizontal fill box in the Layout section is not checked): Display width of the input field.
- Height (Note: Only for Multiple lines input field elements and only if the Vertical fill box in the Layout section is not checked): Height of the input field.
- Align within the column (Note: Only if the Left box is selected in the Label section): Used to indicate if the input field should be aligned with the other labels in the column (box is checked) or if its original position should be kept (box is not checked).
Rows and columns (Note: Only for Group of fields elements): Used to specify the number of rows and columns for cells in the group of fields.
example Group of fields with two rows and four columns
Type and Validation tab
Note: Except for Group of fields and Label elements):
Used to manage the validation behavior of the form element selected in the Conception pane.
Input type (Note: Only for Input field, Password field and Multiple lines input field elements): Used to specify the type of input for users when completing the form element, e.g. string of characters, numeric value, etc.
Show empty value (Note: Only for Single choice list of values elements): Used to specify if an empty item should be displayed in the list of values (box is checked) or not (box is not checked). If an empty item is displayed, it will appear at the top of the list.
Dynamic Field (Note: Only for Input field, Password field, Multiple choice list of values and Single choice list of values elements): Used to specify if the form element is a dynamic field (box is checked) or a static field (box is not checked). If it is dynamic, a computing procedure will run each time the field value changes and the page will be refreshed.
Validating (Note: Only for Input field, Password field and Multiple lines input field elements): Options for defining the behavior of the input field.
- Input is read-only: Users cannot modify the field.
- Input is required: Users must enter a value.
- Mandatory fields are indicated by the asterisk ( *).
- An error message will appear and users will be prevented from moving on to the next step until the field is completed.
Add validation filter on the field (Note: Only for Input field, Password field and Multiple lines input field elements): Used to add validation conditions for a field in order to force users to respect a data entry format. See the procedure.
- You can apply several conditions to a given input field. In this case, all of them must be respected.
- The list of operators, e.g. equal to, starts with, contains, etc. is defined by EasyVista. You cannot add new ones.
- You can define a blocking error message when user input does not respect the validation conditions of the filter.
Input/Output tab
Note: Except for Group of fields elements.
Used to manage input and output variables for the form element selected in the Conception pane, and to refresh the lists of values.
Normal mode
Default Value:
- For Input field, Password field and Multiple lines input field and Label elements: Value displayed by default for the form element.
- This may be a text (Simple) or a script (Expression). Simple option: The text will replace the label of the element. Expression option: The script will run when the form is opened.
- For Multiple choice list of values and Single choice list of values elements: Number of items in the list of values for the form element.
- Click Update list to refresh the list.
See How to specify a list of values.
- Click Update list to refresh the list.
Fixed list values (Note: Only for Multiple choice list of values and Single choice list of values elements): Number of items in the list of values for the form element.
Linked library variable (Note: Except for Label elements): Name of the library variable linked to the form element.
- A library variable can be created as an input and output variable.
- You can modify the names of variables in Advanced mode.
- For List of values elements, this can be:
- A simple variable for a single choice list of values.
- A table for a multiple choice list of values.
Advanced Mode
Values of the list (Note: Only for Multiple choice list of values and Single choice list of values elements): Used to specify how items in the list of values are initialized. See Best practice.
- Values of the list (default option): The values are the items added to the list when the element was created (Values of the list option).
- Click Update list to refresh them.
See How to specify a list of values.
- You can export them to the Self Help project library and use them in forms in another project.
- Click Update list to refresh them.
- Project Library: Items in the list are initialized using variables from the Self Help project library.
- Click Update to modify the properties of the list of values.
- Click Update to select another variable from the library.
- Parameter: Items in the list are initialized using an input parameter.
Input value: Used to specify how the input value associated with the form element will be initialized.
- The value can be a variable from the Self Help project library, a parameter or a free expression linked to a form element (Fixed value).
Output value (Note: Except for Label elements): Used to specify how the form element value specified by the user will be stored.
- The value can be a variable from the Self Help project library or a parameter.
See How to specify the parameters of a form.
Procedures
See detailed step by step on Self Help portal
How to create a form
Step 1: Select the Self Help project.
1. Select the Self Help project in the tree structure of the Explorer pane.
2. Click to display the tree structure.
Step 2: Create the form.
1. Right-click the folder where you want to create the new form.
2. Select New > Form from the contextual menu.
The form will be inserted in the Explorer pane. Its name will be <New form>.
3. Rename the form.
The Explorer pane will be refreshed.
Step 3: Initialize the structure of the form.
1. Double-click the form in the Explorer pane.
- The Conception pane will appear.
- The first cell in the form will appear.
2. Specify the number of rows and columns for your form.
- Click outside the form in the workspace in the Conception pane.
The Global form properties tab will appear in the Description pane. - Specify the format you want.
The form will be refreshed.
3. You can add rows and columns individually.
- Click
at the bottom of the form to add a row.
- Click
to the right of the form to add a column.
Step 4: Design the form.
1. Click inside a cell and select the type of element you want to add from the contextual menu.
See Types of elements in forms.
2. Specify the element depending on its type, e.g. list of values, input field, etc. and click Finish.
See the detailed procedures.
3. Repeat the procedure to add other cells in the form.
Modify the contents of a cell
- Click the cell in the Conception pane.
A blue outline will appear.
- Make your changes in the Description pane.
See the description of properties.
Note:Used to indicate that errors were detected, e.g. name not specified, error with a condition, etc. Move the cursor over the icon to display its details in a tooltip.
4. Edit the layout of the form.
See the advanced procedures.
Step 5: Check that the form is correctly displayed.
1. Insert the form in one of the steps of your procedure.
- Double-click the procedure in the tree structure of the Explorer pane.
The procedure will appear in the Conception pane.
- Click and drag the form from the Explorer pane to the relevant step in the Conception pane.
2. Check the workability of the form.
- Click
in the toolbar of the Conception pane.
- Select
Launch the procedure.
- The step will run.
- The form will appear in your Web browser.
- Check that the form works correctly.
Detailed procedures
How to create a form element with input
Input field, Password field and Multiple lines input field elements
Note: The form element is made up of a label and an input field.
Step 1: Create the form element.
1. Right-click an empty cell in the form in the Conception pane.
2. Select Add from the contextual menu and click the type of element you want to add.
The properties window will appear.
3. Enter the label of the input field.
Note: This label will appear when the form is accessed in execute mode, and will be displayed to users.
4. Select the type of input field for the form element, e.g. string of characters, numeric value, etc.
Note: You can modify this subsequently in the Type and Validation tab in the Description pane.
5. Select the Required field box if you want users to complete this field.
Step 2 (optional): Specify input and output parameters for the field.
1. Select the Manual management option if you want to map parameters with existing variables in the project manually.
Note: The default option, From project library, is used to generate parameters in the project library automatically using the title of the field.
example Other information field ==> Name of parameters: Other_information
Step 3 (optional): Define the layout of the form element.
1. Specify the exact display width, in pixels, of the form element, i.e. label and input field, in the Field size field.
2. Select the Align label on column size option to align the label of the field with the other labels in the column.
3. Select the Forced size (text size if empty) option to specify the exact display width of the label.
Note: By default, the display width will automatically be adjusted to the size of the label.
Step 4: Save the form element.
1. Click Finish.
- The new form element will be inserted in the Conception pane.
*The Description pane will appear.
Step 5 (optional): Enhance the behavior and layout of the form element.
1. Make the required modifications to the behavior of the form element, e.g. validation filters, type of input, etc. using the properties in the Type and Validation tab in the Description pane.
2. Enhance the layout of the form element using the properties in the Display tab in the Description pane.
See the advanced procedures.
3. Adapt the input and output parameters of the form element using the properties in the Input/Output tab in the Description pane.
How to create a list of values
Multiple choice list of values and Single choice list of values elements
Note: The form element is made up of a label and a list of values.
Step 1: Create the form element.
1. Right-click an empty cell in the form in the Conception pane.
2. Select Add from the contextual menu and click the type of element you want to add.
The properties window will appear.
3. Enter the label of the list of values.
Note: This label will appear when the form is accessed in execute mode, and will be displayed to users.
4. Select the Required field box if you want users to select one or more values from the list.
Step 2 (optional): Specify input and output parameters for the field.
1. Select the Manual management option if you want to map parameters with existing variables in the project manually.
Note: The default option, From project library, is used to generate parameters in the project library automatically using the title of the field.
example Other information field ==> Name of parameters: Other_information
Step 3: Define the items in the list of values.
Enter items manually
1. Click Create list.
The window for entering values will appear.
2. Click Add only Label.
Note: By default, each value is associated with a form variable with the label name.
Click Add Label/Value if you want to name variables manually.
3. Enter the label of the value in the Label column.
Note: The label is the text that users will see in the list.
4. (optional) Enter the name of the variable associated with the label in the Value column.
Note: This value is not displayed in the list.
5. Repeat the procedure for each item in the list.
6. Click Finish.
Create items using existing project variables
1. Click Add variable.
The list of object variables will appear.
2. Select the project variable to be associated with the item in the list of values.
Step 4 (optional): Define the layout of the form element.
1. Specify the exact display width, in pixels, of the form element, i.e. label and list of values, in the Field size field.
2. Select the Align label on column size option to align the label of the field with the other labels in the column.
3. Select the Forced size (text size if empty) option to specify the exact display width of the label.
Note: By default, the display width will automatically be adjusted to the size of the label.
Step 5: Save the form element.
1. Click Finish.
- The new form element will be inserted in the Conception pane.
*The Description pane will appear.
Step 6 (optional): Enhance the behavior and layout of the form element.
1. Indicate the display mode for the list of values.
- Select the Display tab in the Description pane.
- Select the display mode in the Selector appearance field.
See Display modes for lists of values.
- (Note: Only for buttons, radio buttons and checkboxes) Select the Horizontal box to display all values in a single row.
2. Make the required modifications to the behavior of the form element, e.g. empty value, or dynamic field, using the properties in the Type and Validation tab in the Description pane.
3. Enhance the layout of the form element using the properties in the Display tab in the Description pane.
See the advanced procedures.
4. Adapt the input and output parameters of the form element using the properties in the Input/Output tab in the Description pane.
Configure the form parameters
Advanced procedures
How to enhance the layout of a form
Merge cells to display a form element
example Merge two rows to display an input field
1. Click the form element in the Conception pane.
2. Select the Display tab in the Description pane.
3. Specify the number of rows and columns occupied by the element in the Layout tab.
4. Enhance the display using the other properties in the section.
- Select the Horizontal fill box if you want the form element to occupy the entire width of the cell.
- Select the Vertical fill box if you want the form element to occupy the entire height of the cell.
- Select the position of the label field as regards the input field.
5. Click in the toolbar of the Conception pane to save the form.
Adjust the display of the label field and input field for the form element
1. Click the form element in the Conception pane.
2. Select the Display tab in the Description pane.
3. Adjust the label field using the properties in the Label section.
- Specify the display width of the label field.
- Select the position of the label field as regards the input field.
4. Adjust the input field using the properties in the Input field section.
- Note: (Only if the Horizontal fill box is not checked) Specify the exact display width of the input field.
- Note: Only for lists of values.
- Select the display mode for the list of values in the Selector appearance field.
See the description.
- (Note: Only for buttons, radio buttons and checkboxes) Select the Horizontal box to display all values in a single row.
- Select the display mode for the list of values in the Selector appearance field.
5. Click in the toolbar of the Conception pane to save the form.
How to add a validation filter
Input field, Password field and Multiple lines input field elements
Step 1: Select the form element.
1. Click the cell containing the form element in the Conception pane.
The properties of the element will appear in the Description pane.
Step 2: Define the validation filter.
1. Select the Type and Validation tab in the Description pane.
2. Click Add validation filter on the field.
3. Define the first filter condition.
- Select the operator from the drop-down list.
Note: To define a condition built using a regular expression, select the Regexp operator.
- Double-click the right column and specify the authorized value.
Note: Conditions for the Email, Phone and French Postal Code operators are predefined. You cannot enter any value.
4. Repeat the procedure for the other filter conditions.
5. (optional) Type the error message to be displayed when user input does not respect the validation filter conditions.
example ID input field
- Regexp operator; Value=[a-zA-Z]{4}[0-9]{4}. ==> User input must consist of four letters in the upper or lower case, followed by four numbers
- Error message: Your ID is incorrect. It must consist of four letters in the upper or lower case, followed by four numbers.
Step 3: Test the validation filter.
1. Click in the toolbar of the Conception pane to save the form.
2. Run the procedure that includes the form.
See How to display a form in a procedure step.
3. Enter an incorrect value in the input field where you applied the validation filter.
4. Check that the filter conditions prevent user input and that the error message is displayed.
How to use a form in a procedure
How to display a form in a procedure step
1. Double-click the procedure in the tree structure of the Explorer pane.
The procedure will appear in the Conception pane.
2. Click and drag the form from the Explorer pane to the relevant step in the Conception pane.
The form will appear as a resource used by the step.
3. Run the procedure to test that the form is correctly displayed in the step.
How to use form variables in procedure steps
See the use case.
Note: The steps where form data is used must be defined after the step where the form was inserted.
Step 1: Insert form variables in a step.
1. Double-click the procedure in the tree structure of the Explorer pane.
The procedure will appear in the Conception pane.
2. Click the step that will display form data in the Conception pane.
The content of the step will appear in the Description pane.
3. Insert text in the Content tab of the Description pane.
4. Click and drag the form variable from the Explorer pane to the Content tab, and place it just after the text you previously inserted.
5. Repeat the procedure to add the other form variables.
Step 2: Check that the form is correctly displayed.
1. Run the procedure.
2. Answer the questions in the form.
3. Move through the procedure until the step where the form values are displayed.
4. Check that your answers are correctly displayed.
Use cases
Create a standard form
See the detailed procedure
This use case describes a form that enables users to know if they are eligible for a new smartphone based on their answers. Users must have worked two or more years for the company and be required to travel for business frequently.
Create a dynamic form
See the detailed procedure
This use case describes a dynamic form that displays the different logos of EasyVista products on a given page depending on the user's options and to refresh the page based on the user's selected options.