Customized request forms
- name:
- Customized request forms
- description:
- Define personalized request forms based on the service catalog. Add extra fields for a given type of request.
- version:
- 2.0.14
- release:
- 2019-01-24
- itop-version-min:
- 2.3.2
- code:
- combodo-customized-request-forms
- state:
- stable
- alternate-name:
- Request Templates
- diffusion:
- iTop Hub
Features
This module provides the capability to add dynamically additional fields on a User Request in order to better qualify it. The additional fields proposed will be different based on the selected Service / Service Subcategory.
For instance when a user asks for a “new virtual machine”, then
we may want him to provide the number of CPUs, the quantity of RAM
and the type of OS in
structured fields rather than hoping that the user will provide
them by himself, in the Description field.
You just have to define your template and then when a user creates a ticket, the additional fields will appear in the ticket edition form, based on the selected service subcategory.
A request template is related to a service subcategory. A request template can add one or multiple additional fields to User Requests. The additional fields can be of the following types:
-
Date and Date Time
-
String (formated with regular expression if needed)
-
Text area
-
CSV list
-
List based on OQL query
-
Duration
-
Readonly/hidden fields
Revision History
| Release Date | Version | Comments |
|---|---|---|
| 2019-01-30 | 2.0.14 | Fix regression introduced in 2.0.10: custom date formats no longer working |
| 2018-12-19 | 2.0.13 | - Fix unnecessary error messages popping on the
screen when a DoCheckToWrite fails - Fix execution notice (check array existence) - Update spanish translations (thanks to Miguel Turrubiates!) |
| 2018-06-27 | 2.0.12 | Add DE translation |
| 2018-06-26 | 2.0.11 | ES + BR translations, default search attributes |
| 2018-01-26 | 2.0.10 | Ticket fields can now be used in customized
forms. Also fixed 2 bugs for usage in notifications templates ($service_details$) : - N°1079 When the user leaves it undefined, then this is shown as an error message in the email: “Custom field error: Wrong format: missing template_data” ; - N°1080 When a field aims at selecting an object, the email body shows the id of the selected object. |
| 2018-01-05 | 2.0.9 | Customized forms are now compatible with Incident |
| 2017-11-13 | 2.0.8 | Service_details is now documented on UserRequest creation before notification |
| 2017-09-08 | 2.0.7 | Request template value not set in notification when creating an object |
| 2017-03-01 | 2.0.6 | Added module setting to reset template fields value when changing to a different template that contains fields with same codes |
| 2016-12-13 | 2.0.5 | Fixed issues when used in cunjunction with the legacy portal. Requires iTop > 2.3.2 for the date/time pickers to work fine |
| 2016-11-29 | 2.0.4 | Implemented placeholders (e.g. $this->html(service_details)$. Requires iTop > 2.3.1 for the placeholders to work fine. |
| 2016-09-08 | 2.0.3 | Added validation pattern to Date and DateTime fields. Fixed a PHP Warning when launching the cron manually. |
| 2016-09-02 | 2.0.2 | Hidden and Read-only fields are now rendered like multiline strings (like a textarea, though it is read-only) - Note that this will work fine in the console with iTop 2.3.0+, but requires iTop > 2.3.1 to take advantage of this enhancement in the enhanced customer portal (no change in the legacy portal!) |
| 2016-08-03 | 2.0.1 | Support of the console and the enhanced customer portal (both require iTop 2.3.0, otherwise the behavior is the same as 1.0.5) |
| 2015-11-26 | 1.0.5 | Fix for crash when submitting a ticket from the portal for a template with an ENUM field containing some special characters. |
| 2015-09-29 | 1.0.4 | Fix for a crash when a “drop-down list” field contains some weird characters (accents, question marks…) at the beginning of the list of values. |
| 2014-12-10 | 1.0.3 | Cosmetics on the module name. |
| 2014-04-03 | 1.0.2 | Minor fix to allow non admin users to import Template fields in CSV. |
| 2014-03-10 | 1.0.1 | Bug fix for template fields with the same name as an attribute of the object. |
| 2014-02-05 | 1.0.0 | First version, never validated. |
Limitations
The placeholders will not work with iTop 2.3.1 and older.
Installation & upgrade
-
Download the package and expand its content into the “extensions” directory of iTop.
-
If you have already installed iTop, make sure that the configuration file
config-itopinconf/productionis NOT read-only. -
Point your web browser to
http(s)://<your_itop_root>/setupand follow the wizard instructions. Make sure that you select the option to “Upgrade an existing iTop instance”:
-
Finally check the module “Request template” in the list of extensions at the end of the interactive wizard. Then complete the installation.
Configuration
The following settings can be adjusted in the iTop configuration
file, in the section itop-request-template:
| Parameter | Type | Description | Default Value |
|---|---|---|---|
| copy_to_log | string | The attribute into which the template values should be copied. Set to an empty string to disable this behavior. | public_log |
The following settings can be adjusted in the iTop configuration
file, in the section templates-base:
| Parameter | Type | Description | Default Value |
|---|---|---|---|
| hidden_fields_profiles | string | CSV list of profiles. If the user has ANY of the listed profile, she will NOT see the fields of type “hidden”. | Portal user |
| reset_fields_on_template_change | boolean | If set to “true”, fields value will be reset when changing template, even if some of the fields have the same code. | false |
| view_extra_data | string | FIXME | relations |
Usage
Create request template
From the Service Management menu, click on “Request template”:
The pages show a list of already defined request templates. Click on the button “new” to create a new one:
A request template is identified by its name the related service and service sub category.
The label is used on the portal to select a template if several are defined for a given service sub category.
The tab “Fields” is used to define the fields of the template:
Click on “Create a new field” to define a new one:
Here is a complete description of the properties:
| Property | Description | Example |
|---|---|---|
| Code | Unique identifier, that can be used in the queries defined in another field. This value must be made of alphanumeric characters and cannot start with a number | model |
| Order | An integer that defines in which order the fields are displayed in the form | 3 |
| Label | Label seen by the user who is prompted for entering a value | Device Model |
| Mandatory | Wether or not the user must enter/select a value | yes |
| Input type | … see a detailed description hereabove | List |
| Values (OQL or CSV) | Used for drop-down lists only to
define the list of allowed values for this element. This can be
either a comma separated list of values (e.g.
“high,medium,low”). The OQL can have a parameter in
the form :template->code, where code is the code of
another field. It can also use placeholder like
:current_contact->org_id or
:this->org_id which refer to the customer of the
Ticket |
SELECT Model WHERE brand_id = :template->brand |
| Initial value | Used to set an initial value for text or text area fields | xyz |
| Format | Allows you to define a regular expression for validating text fields | ^[a-zA-Z]$ |
| To limit to … | use this regex within Format |
| an email | [a-zA-Z0-9._&'-]+@[a-zA-Z0-9.-]+\.[a-zA-Z0-9-]{2,} |
| a phone number | ^\+?[0-9\ ]{8,20}$ |
| a url | https?,ftp)\://([a-zA-Z0-9+!*(),;?&=\$_.-]+(\:[a-zA-Z0-9+!*(),;?&=\$_.-]+)?@)?([a-zA-Z0-9-.]{3,})(\:[0-9]{2,5})?(/([a-zA-Z0-9%+\$_-]\.?)+)*/?(\?[a-zA-Z+&\$_.-][a-zA-Z0-9;:[\]@&%=+/\$_.-]*)?(#[a-zA-Z_.-][a-zA-Z0-9+\$_.-]*)? |
The input type can have one of the following values:
| Input type | Description |
|---|---|
| Date | A pure date, entered by the mean of a calendar, or directly typed in |
| Date and time | Date and time, entered by the mean of a calendar, or directly typed in |
| Drop-down list | A list as defined by the property Values |
| Duration | A time lapse |
| Hidden | A value that will not be seen by the end-user (customer portal), but it will be seen by an agent (console). The value is set by the mean of the property Initial value |
| List | A value to select amongst a list of proposed values. These values are defined by the mean of the property Values … |
| Read-only | A value defined in Initial value, and which cannot be modified by anybody |
| Text | A single line of text, which format may be enforced by setting Format |
| Text area | A text with several lines |
The tab “Preview” displays a preview of the template as it will be displayed in the console:
Behavior on the Customer Portal
If a end-user selects a service sub-category on the customer portal which is related to a request template, the specific fields for this template are displayed, grouped under the denomination Service details.
This additional information is copied into the Public log when the User Request is created:
It is also possible for a Support Agent to see or edit the information in the details of the User Request, from the console:
Template placeholders
In a notification template, or anywhere else where a template can be used, the following placeholders will be available.
Assuming that this is a UserRequest:
-
$this->service_details$: a plain text representation of the selected values. This is suitable for a plain text email. Though it seems possible to use it within an HTML document, by using a PRE tag, this is NOT recommended because HTML entities (like <) still need to be escaped.
-
$this->html(service_details)$: an HTML representation of the selected values.
Hidden fields are forcibly excluded from the placeholders.
When a template value corresponds to an object selected into iTop, the returned value will be the friendly name of the object.
Questions & Answers
Question: Can I get the UserRequest which do not have a
associated Request Template
Answer: Yes & No.
Query like this will fails
SELECT UserRequest WHERE ISNULL(service_details) = 1
While such query will work, with the limitation that if you have added or removed Request Template to service subcategories after the creation of User Request using those service Subcategories, then the result will be wrong.
SELECT u,rt FROM UserRequest AS u JOIN ServiceSubcategory AS ss ON u.servicesubcategory_id=ss.id JOIN RequestTemplate AS rt ON rt.servicesubcategory_id=ss.id WHERE ISNULL(rt.name) = 1