User Tools

Site Tools



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

Link to this comparison view

extensions:itop-object-copier_1_0 [2018/12/19 11:40] (current)
Line 1: Line 1:
 +====== Object copier ======
 +---- dataentry summary ----
 +name             : Object Copier
 +index_hidden ​    : no
 +version ​         : 1.0.3
 +release_dt ​      : 2014-12-18
 +description_wiki : Provides end-users with a shortcut to clone CIs or create child requests, or even clone with transformations
 +itop-versions ​   : 2.0.2
 +keyword_tags ​    : shortcut, productivity
 +dependencies_s ​  : none
 +download_url ​    : http://​​itop-extensions/​
 +<​related_components>​Other versions of this component:</​related_components>​
 +This extensions aims at improving the end-users productivity. It adds a menu to create an item prefilled with information coming from an existing item.
 +Amongst the possible usages, you can:
 +  * Provide a mean to quickly clone CIs (clone all the attributes but still force the user to enter a new name)
 +  * Provide a shortcut to create a ticket from a Contact that will be the caller of the ticket
 +  * Provide a shortcut to create a parent ticket (and record the information into the child ticket)
 +  * Provide a shortcut to create a ticket from a CI (and record the information into the child ticket)
 +  * Provide a shortcut to create a change ticket from a user request (and record the information into the user request)
 +Let's use the last example to illustrate the possibilities of the module:
 +Users have a menu in the **Other Actions** drop-down menu of a //User Request//:
 +Clicking on the menu, opens the standard creation form with prepopulated data:
 +The user can adjust the values, then create the item.
 +In addition to the standard report, a message indicates that something has been retrofitted back to the //source// item.
 +===== Principles =====
 +A shortcut is governed by a //rule definition//​.
 +The menu is visible if a series of conditions are met:
 +  * The item being visited is in the scope of the rule (given by an OQL). For instance, you may want to propose the shortcut only for user request being assigned or pending: SELECT UserRequest WHERE status IN ('​assigned',​ '​pending'​)
 +  * The current user has a profile allowed for the rule (can be anybody)
 +Several rules can coexist for a single //source object//: there will be as many menus as there are rules that match the conditions.
 +A rule defines which kind of object to create:
 +  * Either a given class (can be an abstract class, the user will have to select a subclass)
 +  * Or the exact same class as the //source object//
 +A rule specifies what has to be done to //preset// or //​prepopulate//​ the form. This is done by the mean of //​actions//​.
 +The following kind of actions are available:
 +  * Set the value of an attribute depending on the value of one or several attributes from the //source object//.
 +  * Copy the N-N links
 +  * Add an N-N link to the //source object// or to an external key of the //source object//.
 +Additionaly,​ the rule specifies what has to be done to //​retrofit//​ some information from the //created object// to the //source object//.
 +===== Limitations =====
 +The following types of attributes are currently not handled and therefore cannot be preset (and no error message is given):
 +  * 1-N links (e.g. Server Interfaces)
 +  * Attachments
 +  * Blobs
 +  * Stop watches
 +Using //​apply_stimulus()//​ on the //created object// does not work. 
 +//If used in preset, the form is shown with the object id and the relevant buttons depending on the new state but then it fails to "​create"​ the object because it was created already during the stimuli processing//​
 +===== Requirements =====
 +===== Revision History =====
 +^  Version ​ ^  Release Date  ^  Comments ​ ^
 +|  1.0.3  |  2014-12-18 ​ | Translated the default configuration in french (while keeping the engish version as the default) |
 +|  1.0.2  |  2014-07-18 ​ | Added placeholders for set() and append(): $current_contact_id$ (already documented) and $current_contact_friendlyname$ (new!) |
 +|  1.0.1  |  2014-04-03 ​ | Fixes an issue with linksets: the links were correctly created into the clone, but they were deleted from the source object |
 +|  1.0.0  |  2014-03-04 ​ | First officialy released version |
 +===== Installation =====
 +Copy the folder ''​itop-object-copier''​ into the ''​extensions''​ folder of iTop and launch the setup again.
 +<note warning>​Make sure that the web server has enough rights to read the content of the ''​extensions''​ folder and all its sub-folders before launching the setup</​note>​
 +When prompted to select the extensions to install, check "​Object copier"​ in the list of available extensions.
 +===== Configuration =====
 +^ Setting name ^ Description ^ Example ^
 +| source_scope| The OQL to define the //source objects//. The only parameter available is //​current_contact_id//​ | "​SELECT UserRequest WHERE status = '​assigned'"​ |
 +| allowed_profiles | CSV list of profiles allowing the shortcut. The user must have at least one profile to have the shortcut available. Wrong profiles names are ignored. Set as an empty string to allow the shortcut to anybody. | "​Administrator,​Support Agent" |
 +| menu_label | Optional: Label or dictionary entry for the new menu entry. It is optional and defaults to "​Clone..."​ | |
 +| form_label | Optional: Label or dictionary entry for the form header. It is optional and defaults to "​Cloning %1$s" | |
 +| report_label | Optional: Label or dictionary entry for the report once the object has been created. It is optional and defaults to "​Cloned from %1$s" | |
 +| dest_class | Class of the object to create. If empty, it defaults to the class of the source object | "​Change"​ |
 +| preset | Array of actions to preset the object in the creation form. More information above | array() |
 +| retrofit| Array of actions to retrofit some information from the created object to the source object. More information above | array() |
 +<note tip>​menu_label,​ form_label and report_label can be localized without the burden of create dictionaries. To do so, create the settings menu_label/<​language_code>​ (e.g. "​menu_label/​FR FR") for each supported language. The setting menu_label will be the default value.</​note>​
 +An action is specified as a string having formatted as "​verb(arg1[,​arg2[...]])"​
 +The following //verbs// are available:
 +^ Verb ^ Parameters ^ Description ^
 +| clone_scalars | <​none>​ | Copy all the scalar attributes |
 +| clone | attcode1,​attcode2,​ ... | Copy the given attributes |
 +| reset | attcode | Reset the attribute to its default value |
 +| copy | att_to_read,​att_to_write | Copy from att_to_read to att_to_write |
 +| append | attcode,​string | Append the string to the attribute. The string can contain placeholder like <​nowiki>​$this->​attcode$</​nowiki>​ (or $current_contact_id$ or $current_contact_friendlyname$). Commas must be escaped with a backslash. Newlines (\n) are allowed. The character set must be utf-8. |
 +| set | attcode,​value | Set a value. If the value is a string, it can then contain placeholder like <​nowiki>​$this->​attcode$</​nowiki>​ (or $current_contact_id$ or $current_contact_friendlyname$). Commas must be escaped with a backslash. Newlines (\n) are allowed. The character set must be utf-8. |
 +| add_to_list | attRead,​attWrite,​attLink,​value | attRead is an external key on the read object, attWrite is a N-N link set on the written object, attLink is an attribute on the link class that will be set to <​value>​ |
 +===== Configuration example =====
 +<code php>
 +'​itop-object-copier'​ => array(
 + '​rules'​ => array(
 + array(
 + '​source_scope'​ => '​SELECT UserRequest WHERE status IN ("​assigned",​ "​pending"​)',​
 + '​allowed_profiles'​ => '​Administrator,​Support Agent',​
 + '​menu_label'​ => 'Issue a change ticket...',​
 + '​form_label'​ => 'Issue a change from request %1$s. Please review the description before create the change ticket. After creation of the change ticket, the request ticket will be automatically updated.',​
 + '​report_label'​ => '​Issued from the request %1$s. The request has been updated.',​
 + '​dest_class'​ => '​Change',​
 + '​preset'​ => array(
 + '​clone(contacts_list,​functionalcis_list,​org_id,​title,​caller_id)',​
 + '​set(description,​Original description:​\n\$this->​description\$)',​
 + ),
 + '​retrofit'​ => array(
 + '​copy(id,​ parent_change_id)',​
 + '​set(private_log,​Issued change $this->​ref$)',​
 + ),
 + ),
 + array(
 + '​source_scope'​ => '​SELECT FunctionalCI',​
 + '​allowed_profiles'​ => '',​
 + '​dest_class'​ => '',​
 + '​preset'​ => array(
 + '​clone_scalars(*)',​
 + '​reset(name)',​
 + ),
 + '​retrofit'​ => array(
 + ),
 + ),
 + ),
 +===== Troubleshooting =====
 +All errors are logged to the file log/​error.log
 +The behavior from the end-user perspective is:
 +  * When the parameters source_scope is wrong, the rule is ignored
 +  * When dest_class is not a valid class, the rule is ignored
 +  * When source_scope/​dest_class/​allowed_profiles/​preset/​retrofit are missing, the rule is ignored
 +  * When the list of profiles contain wrong names, those names are simply ignored, and if all the names in the list are wrong then no one will have the menu to clone the object.
 +  * When a preset action is wrong (syntaxically or grammatically),​ the preset is stopped at that point, the form is displayed with a message explaining the issue: "An error has been encountered while presetting the object to create: <error message>​. Please contact your administrator."​ The user can proceed with the object creation.
 +  * When a retrofit action is wrong, the retrofit is stopped at that point, the operation completes (object created as expected) and the report contains: "An error has been encountered while retrofitting some information back to the source object: <error message>​. Please contact your administrator."​
extensions/itop-object-copier_1_0.txt ยท Last modified: 2018/12/19 11:40 (external edit)