User actions configurator

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.

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 N-N links (eg. Documents on a Ticket, while cloning a Ticket. Documents are not duplicated, just the links are)
• Copy 1:n link by duplicating the 1-N linked objects (e.g. Server Interfaces, WorkOrders on a Change)
• 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.

The following types of attributes are currently not handled and therefore cannot be preset (and no error message is given):

• Blobs
• Stop watches
• TagSet (preset but not saved)
• EnumSet (preset but not saved)

If apply_stimulus() is 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

If you copy or set incoherent data in the creation form, this will not be detected. For examples values which do not match the XML filter, a Caller not aligned with the Organization on a UserRequest. It is up to the object copier rule creator to respect the rules. The underlying reason is that iTop does always consider as a valid value, the one which is already set and the values returned by the filter. The reason being that we don't want to remove an existing value in the back of the user. A common example is related Change, which is suppose to be an open change, but the day that Change is closed, we don't want to loose the relationship (this was fixed in 2.4 or 2.5).

Use the Standard installation process for this extension.

An action is specified as a string formatted as verb(arg1[,arg2[…]])
The same action can be requested multiple times.

The following verbs are available:

'itop-object-copier' => array(
    'rules' => array(
        0 => 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 [...]',
                '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: $this->description$)',
                ),
                'retrofit' => array(
                        'copy(id, parent_change_id)',
                        'set(private_log,Issued change $this->ref$)',
                ),
        ),
        1 => array(
                'source_scope' => 'SELECT FunctionalCI',
                'allowed_profiles' => '',
                'dest_class' => '',
                'preset' => array(
                        'clone_scalars(*)',
                        'reset(name)',
                ),
                'retrofit' => array(
                ),
        ),
    ),
),

In the above examples, 0 and 1 are the identifier of the rules.

• You can use a string instead of a number, for identifying an object copier rule (allowed characters: space,A-Za-z0-9_=-).
• Internally the menu UID will be build this way: object_copier_ + the rule id you gave it.
• So UID of the above menus, we will be: object_copier_0 and object_copier_1

Out of the box Configuration

    'itop-object-copier' => array (
       'rules' => array (
          'clone_location' => array (
            'source_scope' => 'SELECT Location',
            'allowed_profiles' => 'Administrator,Configuration Manager',
            'menu_label' => 'Clone...',
            'menu_label/FR FR' => 'Cloner...',
            'menu_tooltip' => 'Clone this location...',
            'menu_tooltip/FR FR' => 'Cloner ce lieu...',
            'icon' => 'fas fa-clone',
            'form_label' => 'Cloning %1$s',
            'form_label/FR FR' => 'Clonage de %1$s',
            'report_label' => 'Cloned from %1$s',
            'report_label/FR FR' => 'Cloné depuis %1$s',
            'dest_class' => 'Location',
            'preset' => array (
              0 => 'clone_scalars(*)',
              1 => 'reset(name)',
            ),
            'retrofit' => array (
            ),
          ),
          'child_userrequest' => array (
            'source_scope' => 'SELECT UserRequest WHERE status NOT IN (\'resolved\',\'closed\')',
            'allowed_profiles' => 'Support Agent,Administrator',
            'menu_label' => 'Create a child request...',
            'menu_label/FR FR' => 'Créer une demande fille...',
            'menu_tooltip' => 'Create a child request of this request...',
            'menu_tooltip/FR FR' => 'Créer une demande fille de cette demande...',
            'icon' => 'fas fa-comment-alt',
            'form_label' => 'Create a child request from %1$s',
            'form_label/FR FR' => 'Créer une demande fille depuis %1$s',
            'report_label' => 'Created from %1$s',
            'report_label/FR FR' => 'Créée depuis %1$s',
            'dest_class' => 'UserRequest',
            'preset' => array (
              0 => 'clone(caller_id,org_id,contacts_list,functionalcis_list)',
              1 => 'copy(id,parent_request_id)',
            ),
            'retrofit' => array (
            ),
          ),
          'userrequest_from_person' => 
          array (
            'source_scope' => 'SELECT Person',
            'allowed_profiles' => 'Support Agent,Administrator',
            'menu_label' => 'Create a user request...',
            'menu_label/FR FR' => 'Créer une demande utilisateur...',
            'menu_tooltip' => 'Create a user request for this person...',
            'menu_tooltip/FR FR' => 'Créer une demande utilisateur pour cette personne...',
            'icon' => 'fas fa-comment-alt',
            'form_label' => 'Create a user request from %1$s',
            'form_label/FR FR' => 'Créer une demande utilisateur pour %1$s',
            'report_label' => 'Created from %1$s',
            'report_label/FR FR' => 'Créée depuis %1$s',
            'dest_class' => 'UserRequest',
            'preset' => 
            array (
              0 => 'copy(org_id,org_id)',
              1 => 'copy(id,caller_id)',
            ),
            'retrofit' => array (
            ),
          ),
          'userrequest_from_ci' => array (
            'source_scope' => 'SELECT FunctionalCI',
            'allowed_profiles' => 'Support Agent,Administrator',
            'menu_label' => 'Create a user request...',
            'menu_label/FR FR' => 'Créer une demande utilisateur...',
            'menu_tooltip' => 'Create a user request for this CI...',
            'menu_tooltip/FR FR' => 'Créer une demande utilisateur pour cet objet...',
            'icon' => 'fas fa-comment-alt',
            'form_label' => 'Create a user request from  %1$s',
            'form_label/FR FR' => 'Créer une demande utilisateur pour %1$s',
            'report_label' => 'Created from %1$s',
            'report_label/FR FR' => 'Créée depuis %1$s',
            'dest_class' => 'UserRequest',
            'preset' => 
            array (
              0 => 'copy(org_id,org_id)',
              1 => 'add_to_list(id,functionalcis_list,impact,Impacted CI)',
            ),
            'retrofit' => array (
            ),
          ),
          'clone_ci' => array (
            'menu_tooltip' => 'Clone this CI...',
            'menu_tooltip/FR FR' => 'Cloner cet élément...',
            'icon' => 'fas fa-clone',
            'source_scope' => 'SELECT FunctionalCI',
            'allowed_profiles' => 'Administrator,Configuration Manager',
            'dest_class' => '',
            'preset' => array (
              0 => 'clone_scalars(*)',
              1 => 'reset(name)',
            ),
            'retrofit' => array (
            ),
          ),
          'userrequest_from_log' => array (
            'source_scope' => 'SELECT UserRequest WHERE status IN (\'closed\')',
            'allowed_profiles' => 'Support Agent,Administrator',
            'menu_label' => 'Create ticket with last log...',
            'menu_label/FR FR' => 'Créer une demande depuis le journal...',
            'menu_tooltip' => 'Create a ticket based on last log entry...',
            'menu_tooltip/FR FR' => 'Créer une demande basée sur la dernière entrée du journal...',
            'icon' => 'far fa-comment-alt',
            'form_label' => 'Create new request from %1$s',
            'form_label/FR FR' => 'Nouvelle demande depuis %1$s',
            'report_label' => 'Created from %1$s',
            'report_label/FR FR' => 'Créée depuis %1$s',
            'dest_class' => 'UserRequest',
            'preset' => array (
              0 => 'clone(caller_id,org_id,contacts_list,functionalcis_list)',
              1 => 'copy(id,parent_request_id)',
              2 => 'copy_head(public_log,description)',
            ),
            'retrofit' => array (
            ),
          ),
        ),
      ),

Here we want to copy a n:n relation, which would be of a similar nature but from 2 different Classes of links, for example you want to create a Change Ticket from a FunctionalCI and automatically retrieve Contacts associated to CI and link them to the Change.

class:Change

public function CopyContactsFromCI($oSource)
{
   // This method should be called from an object copier action triggered from a FunctionalCI.
   $sSourceClass = get_class($oSource);
   if (!MetaModel::IsParentClass('FunctionalCI', $sSourceClass))
   {
      throw new Exception("Wrong source class '$sSourceClass' : 
        CopyContactsFromCI method should be called by a user action associated to a FunctionalCI!");
   }        
   // Problem: method is called twice, when new CreatedObject is displayed and when it is saved, 
   // resulting in executing the code twice.
   // Work around: don't perform operation when CreatedObject is being saved
   $sOperation = utils::ReadPostedParam('operation');
   if ($sOperation == 'apply_new') {  return;  }
 
   $id = $oSource->GetKey();
   // get the ids of Contacts linked to the SourceObject (a FunctionalCI)
   $sOQL = "SELECT lnkContactToFunctionalCI AS l WHERE l.functionalci_id = :id ";
   $oContactSetSrc = new CMDBObjectSet(DBObjectSearch::FromOQL($sOQL), array(), array('id' => $id));
   // ensure you get also the obsolete Contacts objects, in case the user preference hide them
   $oContactSetSrc->SetShowObsoleteData(utils::ShowObsoleteData());
 
   $oContactSetDst = $this->Get('contacts_list');
   // Copy the Contact linked objects one by one
   while ($oLnkSrc = $oContactSetSrc->Fetch())
   {
       $oLnkDst = MetaModel::NewObject('lnkContactToTicket');
       $oLnkDst->Set('contact_id', $oLnkSrc->Get('contact_id'));
       $oContactSetDst->AddItem($oLnkDst);
   }
   $this->Set('contacts_list', $oContactSetDst);
}

Configuration file

  3 => array (
    'source_scope' => 'SELECT FunctionalCI',
    'allowed_profiles' => 'Support Agent,Administrator',
    'menu_label' => 'Create a change...',
    'form_label' => 'Create a user request from  %1$s',
    'report_label' => 'Created from %1$s',
    'dest_class' => 'Change',
    'preset' => array (
         0 => 'copy(org_id,org_id)',
         1 => 'add_to_list(id,functionalcis_list,impact,Impacted CI)',
         2 => 'call_method(CopyContactsFromCI)',
         ),
    'retrofit' => array (),
),

Example: to display the Clone… menu (rule id=1) in the toolbar after the New… and Modify.. buttons, set this:

  'shortcut_actions' => 'UI:Menu:Modify,UI:Menu:New,object_copier_1',

The result will look like this:

If the specified menu is not available for a given class, it's silently not displayed

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.”

Q: When I try to copy a LinkedSet attributes such as contacts_list from a Ticket to a FunctionalCI, it fails, why?
A: Also the attribute contacts_list may look similar on a Ticket, a FunctionalCI, in reality those sets contain objects which are absolutely different, they do not belong to the same class: lnkContactToTicket versus lnkContactToFunctionalCI, which is a mandatory requirement for the copy to work.
The workaround to associate all contacts linked to the Ticket, to the FunctionalCI while creating it, is to use a PHP method as explained above.

Q: When I try to create a Ticket from another one, it first prefill the form but on submission fails and empty all fields, why?
A: A possible cause can be that you are trying to set the status field which is controlling the lifecycle of the created ticket. This is not allowed as this field is read only and can only be changed through the application of a stimulus, which will execute the controls and actions associated with that transition. The error message is not very explicit

Q: Can I add the current object to a LinkedSet attribute of the created object?
A: Yes, this can be done in the retrofit.

Here an example in Simple Request Management, which create an Incident from a UserRequest and link them together in line 14

configuration file

1. 10 => array (
2. 'source_scope' => 'SELECT UserRequest WHERE status NOT IN (\'resolved\',\'closed\')',
3. 'allowed_profiles' => 'Support Agent,Administrator',
4. 'menu_label' => 'Create incident from user request...',
5. 'form_label' => 'Create new incident from %1$s',
6. 'report_label' => 'Created new incident from %1$s',
7. 'dest_class' => 'Incident',
8. 'preset' => array (
9. 0 => 'clone(description,title,org_id,caller_id,team_id,agent_id,service_id)',
10. 1 => 'clone(servicesubcategory_id, contacts_list,functionalcis_list,workorders_list)',
11. ),
12. 'retrofit' => array (
13. 0 => 'set(private_log,Converted to incident $this->hyperlink()$.)',
14. 1 => 'set(parent_request_id,$this->id$)',
15. 2 => 'apply_stimulus(ev_autoresolve)',
16. 3 => 'apply_stimulus(ev_close)',
17. ),
18. ),

Q: Can I delete the source object after cloning?
A: You can invoke in the retrofit, a method to delete the source object, it will do the job, but it displays a red top bar error message, because the retrofit process does not expect the Source object to be gone in the middle of its work. There is no real issue but the error can be misleading for users who read it.

class:MyObject

public function DeleteSource($oObject) 
{  $this->DBDelete(); }

configuration file

        'retrofit' => array (
          0 => 'call_method(DeleteSource)',
        ),

Q: Can I copy the Request Template (service_details) while cloning a UserRequest?
A: No. It is currently not working correctly.

Q: Can I copy the Caselogs while cloning a Ticket?
A: It is covered by this extension, except for versions between 1.3.2 and 1.3.4.
In 1.3.5, there is an known issue, it duplicates the entry made during the cloned object creation.

Q: Can I copy the WorkOrders while cloning a Ticket?
A: It is covered by this extension, except for versions between 1.3.2 and 1.3.4.

So here is a workaround: you can write a method to do it.

• Limitations: Sub-objects are copied in the background on form submission. You will have to modify or delete those that are not applicable after.

Class::Ticket

public function CloneWorkorders($oSource)
{
    // Method called by Object-Copier
    // Change those 2 strings to match your needs
    $sAllowedSourceClass = 'Ticket'; // Class of the SourceObject
    $sSetAttCode = 'workorders_list'; // Attribute code of the n-1 relation to copy
 
    if (!MetaModel::IsValidAttCode(get_class($this), $sSetAttCode))
    {
        throw new Exception(__METHOD__.":Unknown attribute ".get_class($this)."::".$sSetAttCode);
    }
    if (!MetaModel::IsParentClass($sAllowedSourceClass, get_class($oSource)))
    {
        throw new Exception(__METHOD__.":Wrong source class 'get_class($oSource)' : 
            This method should be called by a user action associated to a '$sAllowedSourceClass'");
    }
    // Check that AttributeDef is an AttributeLinkedSet
    $oSourceAttDef = MetaModel::GetAttributeDef(get_class($oSource), $sSetAttCode);
    if (is_object($oSourceAttDef) && !$oSourceAttDef->IsLinkSet())
    {
        throw new Exception(__METHOD__.":Attribute ".$sSetAttCode
                ." is not a LinkSet on class ".get_class($this));
    }
    // To avoid confusing the user, we apply this only on submission
    // Otherwise the copied objects seems to appear on the form, but adding or removing some is ignored.
    $sOperation = utils::ReadPostedParam('operation');
    if ($sOperation != 'apply_new')
    {
        return;
    }
 
    $oDestSet = $this->Get($sSetAttCode);       
    $oSet = $oSource->Get($sSetAttCode);
 
    while($oSourceObject = $oSet->Fetch())
    {         
        $sClass = get_class($oSourceObject);
        $oClone = MetaModel::NewObject($sClass);
        foreach(MetaModel::ListAttributeDefs($sClass) as $sAttCode => $oAttDef)
        {
            // As of now, ignore other attribute than scalars
            if ($oAttDef->IsScalar() && $oAttDef->IsWritable())
            {
                $oClone->Set($sAttCode, $oSourceObject->Get($sAttCode));
            }
        }
        $oDestSet->AddItem($oClone);
    }
    $this->Set($sSetAttCode,$oDestSet);
}