User Tools

Site Tools


extensions:request-templates

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
extensions:request-templates [2016/09/14 10:32]
rquetiez [Limitations]
extensions:request-templates [2019/04/23 12:18] (current)
vdumas
Line 1: Line 1:
-====== ​Request Templates ​======+====== ​Customized request forms ======
 ---- dataentry summary ---- ---- dataentry summary ----
-name             : ​Request Templates ​+name             : ​Customized request forms 
 +description_wiki : Define personalized request forms based on the service catalog. Add extra fields for a given type of request.
 index_hidden ​    : yes index_hidden ​    : yes
-version ​         : 1.0.5 +version ​         : 2.0.14 
-release_dt ​      : ​2015-11-26 +release_dt ​      : ​2019-01-24 
-description_wiki : Display additional fields to portal users, depending the selected service +itop-version-min ​: 2.3.2 
-itop-versions ​   ​: 2.0.2, 2.0.3, 2.1.0, 2.2.0 +code             combodo-customized-request-forms 
-keyword_tags ​    : request,template +state            : stable 
-dependencies_s ​  : itop-service-mgmt/2.0.0 or itop-service-mgmt-provider/2.0.0,​itop-request-mgmt/2.0.0 or itop-request-mgmt-itil/2.0.0 +product_hidden ​  : included 
-download_url ​    http://​www.combodo.com/​itop-extensions/​request-templates-1.0.5-125.zip+alias-code_hidden : request-templates 
 +alternate-name   : Request Templates 
 +module-lists_hidden : templates-base/3.0.17, itop-request-template/2.0.5, itop-request-template-portal/1.0.0 
 +diffusion ​       ​iTop Hub
 ---- ----
 +
 +
 +<note warning>​**Compatibility issue**: for iTop version lower than 2.4.0, there is a [[installation#​itop_before_240|special installation/​upgrade process]].</​note>​
 +
 +
 +<note warning>​For iTop versions older than 2.3.2 use a previous version of this component</​note>​
 +
 <​related_components>​Other versions of this component:</​related_components>​ <​related_components>​Other versions of this component:</​related_components>​
  
  
-This module provides the capability to add additional fields for a user request on the user portal ​in order to better qualify it. +This module provides the capability to add additional fields ​(depending on the selected Service / Service subcategory) ​for a User Request ​in order to better qualify it. 
-For instance define the number of cpu, the size of RAM and the type of OS when a user request ​a new virtual machine.+For instance define the number of CPUs, the quantity ​of RAM and the type of OS when a user asks for creating ​a new virtual machine.
  
-{(rater>​id=1|name=request-template|type=rate)} 
  
 ===== Features ===== ===== Features =====
 +
 This module supports the following types of additional fields: This module supports the following types of additional fields:
  
Line 25: Line 36:
   * String (formated with regular expression if needed)   * String (formated with regular expression if needed)
   * Text area   * Text area
-  * CSv list+  * CSV list
   * List based on OQL query   * List based on OQL query
   * Duration   * Duration
 +  * Readonly/​hidden fields
 +
 +A request template is related to a service subcategory.
 +
 +You just have to define your templates: when a user creates a ticket, the additional fields will appear in the ticket edition form, depending on the selected service subcategory.
  
-A request template is related to a service sub category 
  
-Once defined, the fields defined in the template are automatically display on the user portal. 
  
 ===== Revision History ===== ===== Revision History =====
-^  ​Version ​ ​^  ​Release Date  ​^ ​ Comments ​ ^ +^  ​Release Date  ​^  ​Version ​ ​^ ​ Comments ​ ^ 
-|  ​1.0.5  |  2015-11-26 ​ | Fix for crash when submitting a ticket from the portal for a template with an ENUM field containing some special characters. | +|  ​2019-01-30 ​ |  2.0.14 ​ | Fix regression introduced in 2.0.10: custom date formats no longer working | 
-|  1.0.4  ​|  2015-09-29 ​ | 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. | +|  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!) | 
-|  1.0.3  ​|  2014-12-10 ​ | Cosmetics on the module name. | +| 2018-06-27 | 2.0.12 | Add DE translation | 
-|  1.0.2  ​|  2014-04-03 ​ | Minor fix to allow non admin users to import Template fields in CSV. | +| 2018-06-26 | 2.0.11 | ES + BR translations,​ default search attributes | 
-|  1.0.1  ​|  2014-03-10 ​ | Bug fix for template fields with the same name as an attribute of the object. | +|  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. | 
-|  1.0.0  ​|  2014-02-05 ​ | First version, never validated. |+|  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 ===== ===== Limitations =====
  
-This feature is available only in the user portal. It is not possible to add additional fields in the standard ​iTop support agent interface.+The placeholders will not work with iTop 2.3.1 and older.
  
-It is **NOT** possible to use a template field with the same code as an attribute of the ticket (title, description urgency or priority), **unless** you are running an iTop 2.0.3 or more recent version (fixed on 2014-03-11, revision 3097 in SVN)+===== Installation & upgrade =====
  
-===== Requirements ===== +  * Download the package and expand ​its content ​into the "​**extensions**"​ directory of iTop. 
- +<note warning>​**Compatibility issue**: for iTop version lower than 2.4.0, there is a [[installation#​itop_before_240|special installation/​upgrade process]].</​note>​ 
-No requirement +  ​If you have already installed iTop, make sure that the configuration file ''​config-itop''​ in ''​conf/​production''​ is NOT read-only. 
- +  ​Point your web browser to ''<​nowiki>​http(s)://<​your_itop_root>/​setup</​nowiki>''​ and follow the wizard instructions. Make sure that you select the option to "​Upgrade an existing iTop instance":​ {{ :​extensions:​email-upgrade-screenshot1.png?​direct&​300 |}} {{ :​extensions:​email-upgrade-screenshot2.png?​direct&​300 |}} 
-===== Installation ===== +  ​Finally check the module "​Request template"​ in the list of extensions at the end of the interactive wizard. Then complete the installation.
- +
- +
-  - Download the package: [[http://​www.combodo.com/​itop-extensions/​itop-request-template.zip| itop-request-template.zip]] ​and expand ​the 2 folders "​template-base",​ "​itop-request-template" ​into the "​**extensions**"​ directory of iTop. +
-  ​If you have already installed iTop, make sure that the configuration file ''​config-itop''​ in ''​conf/​production''​ is NOT read-only. +
-  ​Point your web browser to ''<​nowiki>​http(s)://<​your_itop_root>/​setup</​nowiki>''​ and follow the wizard instructions. Make sure that you select the option to "​Upgrade an existing iTop instance":​ {{ :​extensions:​email-upgrade-screenshot1.png?​direct&​300 |}} {{ :​extensions:​email-upgrade-screenshot2.png?​direct&​300 |}} +
-  ​Finally check the module "​Request template"​ in the list of extensions at the end of the interactive wizard. Then complete the installation.+
  
 {{ :​extensions:​itop-request-template-install-module.png?​direct&​300 |}} {{ :​extensions:​itop-request-template-install-module.png?​direct&​300 |}}
Line 65: Line 87:
 ===== Configuration ===== ===== Configuration =====
  
-no 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 ===== ===== Usage =====
  
Line 90: Line 121:
 {{ :​extensions:​itop-request-template-create-field.png?​direct&​300 |}} {{ :​extensions:​itop-request-template-create-field.png?​direct&​300 |}}
  
-A field is identified by its code. The label is used to display the field on the portal. +Here is a complete description ​of the properties:
-  * The "​order"​ is an integer that defines in which order the fields are displayed on the user portal. +
-  * "Value OQL or CSV" is used **for drop-down lists only** to define the list of allowed values for this element. This can be either ​comma separated list of values (e.g. "''​high,​medium,​low''"​) or an OQL (e.g. "''​SELECT Service WHERE org_id = 12''"​). +
-  * "​Initial value" is used to set an initial value for text or text area fields +
-  * "​Format"​ allows you to define a regular expression for validating text fields (e.g. "''/​^[a-zA-Z]$/''"​)+
  
-The tab "​Preview"​ displays a preview of the template as it will be displayed ​on the user portal:+^ 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<​nowiki>​-></​nowiki>​code'',​ where code is the code of another field. It can also use placeholder like '':​current_contact<​nowiki>​-></​nowiki>​org_id''​ or '':​this<​nowiki>​-></​nowiki>​org_id''​ which refer to the customer of the Ticket| SELECT Model WHERE brand_id = :​template<​nowiki>​-></​nowiki>​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]$''​ | 
 + 
 + 
 +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:
  
 {{ :​extensions:​itop-request-template-preview.png?​direct&​300 |}} {{ :​extensions:​itop-request-template-preview.png?​direct&​300 |}}
  
-==== Behavior on the user Portal ==== +==== Behavior on the Customer ​Portal ==== 
-If a end-user selects a service sub-category on the user portal which is related to a request template, the specific fields for this template are displayed, ​prompting to enter the additional information.+ 
 +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**. 
 + 
 +{{ :​extensions:​itop-request-template-portal-enhanced.png?​direct&​500 |}} 
 + 
 +This additional information ​is copied into the Public log when the User Request is created: 
 + 
 +{{ :​extensions:​itop-request-template-public-log-enhanced.png?​direct |}} 
 + 
 +It is also possible for a Support Agent to see or edit the information in the details of the User Request, from the console: 
 + 
 +{{ :​extensions:​itop-request-template-console.png?​direct&​500 |}}
  
-{{ :​extensions:​itop-request-template-portal.png?​direct&​400 |}}+==== Template placeholders ====
  
-This additional information is copied in the Public log when the User Request is created.+In a notification template, or anywhere else where a template can be used, the following placeholders will be available.
  
-{{ :extensions:itop-request-template-public-log.png?​direct&​200 |}}+Assuming that //this// is a UserRequest: 
 +  * <​nowiki>​$this->​service_details$:</​nowiki>​ 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. 
 +  * <​nowiki>​$this->​html(service_details)$:</​nowiki>​ an HTML representation of the selected values.
  
-It is also possible for a Support Agent to see the extra information in the tab "Extra Data" in the details of the User Request.+Hidden fields are forcibly excluded from the placeholders.
  
-{{ :​extensions:​itop-request-template-extra-data.png?​direct&​500 |}}+When a template ​value corresponds to an object selected into iTop, the returned value will be the friendly name of the object.
extensions/request-templates.1473841958.txt.gz · Last modified: 2018/12/19 11:40 (external edit)

";