This tutorial will explain how to expand a piece of XML provided in other tutorial to make it compliant with iTop XML tree structure.

In order to make it readable, we are using a true example, which modifies the way the User Portal displays available services and services sub-categories, when creating a new request. By default, iTop displays them in a list, and we will change it to be displayed them by default as a tree structure.

In order to increase the tutorials readability and highlight the XML nodes which need to be changed, the surrounding XML structure will be provided in a simplified path syntax.

• Each level is separated by /
• itop_design is the only possible top tag, it might be omitted sometimes in the wiki syntax, but don't omit it in the XML file.
• tags with a s at the end are usually collections
• Under a collection, you retrieve usually the same tag without s and with a id to differentiate the nodes
• brick@toto means <brick id=“toto”>

Here is the shortest possible syntax for this example, where only one node need to be modified:

itop_design / module_designs / module_design@itop-portal / bricks / brick@services / browse_modes

      <default _delta="redefine">tree</default>

Instead of opening each level of XML tags and then closing them one by one, we will just provide in a single string, representing the tree structure, and put it in the title of the code block.

In general it will be less compressed for better readability:

itop_design / module_designs / module_design@itop-portal / bricks

   <brick id="services">
       <browse_modes>
           <default _delta="redefine">tree</default>
       </browse_modes>
   </brick>

Now this is how you need to expand the above blocks into the full XML structure required by iTop

itop_design / module_designs / module_design@itop-portal / bricks / brick@services / browse_modes

            <!-- block content -->

should be translated into:

<?xml version="1.0" encoding="UTF-8"?>
<itop_design version="1.6">
  <module_designs>
    <module_design id="itop-portal">
      <bricks>
        <brick id="services">
          <browse_modes>
            <!-- Insert here the block content -->
          </browse_modes>
        </brick>
      </bricks>
    </module_design>
  </module_designs>
</itop_design>

Also not part of the simplified syntax, those 2 rows must be documented at the top

<?xml version="1.0" encoding="UTF-8"?>
<itop_design version="1.6">

version=“1.6” correspond to the minimal iTop XML version required by your extension.
The XML version is available since iTop 2.0 and at least until iTop 2.6, can be guessed from the iTop version, by removing 1 to the first digit.

• example: all iTop 2.6.x versions uses an XML version of 1.6
• If you use a XML tag which was added in iTop 2.5 for eg. then don't put an XML version below 1.5

Once you have expanded the simplified XML into the full required structure, copy it into the file datamodel.my-extension.xml of your extension - my-extension being your true extension name - and run the setup or the toolkit to see the result.

For inserting a method, it can only be done in 2 places, in a class or in a module.

• for class we will just provide the class in which the method need to be declared in the box title: class:UserRequest
• for module, no specific syntax exist.

This part explains how to define/overwrite a PHP method on a class.

• Multiple tutorials will tell you to write a PHP method on a class, to implement a new behavior in iTop.
• They may even provide you the exact piece of PHP code,
• But they won't explain how to insert that PHP code into the iTop XML structure.
• This technic, independent of the method itself, is just what we will explain
• To make it less abstract, we are using a true example:

The used example is an extract from a more complex use case, here we only look at declaring a PHP method in XML

In the title box, you will find the class in which the method need to be declared. eg. class:UserRequest

class:UserRequest

public function IncrementCounter($sAttCode, $iIncrement=1)
{
   // Defensive programming, ensure that the field code is valid on current class       
   if (MetaModel::IsValidAttCode(get_class($this), $sAttCode))
   {
       $iNew = $this->Get($sAttCode) + $iIncrement;
       $this->Set($sAttCode, $iNew);
   }
   return true;
}         

The PHP code must be expended before being paste in the file datamodel.my-extension.xml

Here is how it must be expended:

<?xml version="1.0" encoding="UTF-8"?>
<itop_design version="1.3">
  <classes>
    <!-- the class name is found in the title of the simplified syntax box -->
    <class id="UserRequest" _delta="must_exist">
      <methods>
        <!-- any 'id' could work, but easier to remember if equal to function name -->
        <method id="IncrementCounter" _delta="define">
          <static>false</static>
          <access>public</access>
          <!-- comment is optional -->
          <comment><![CDATA[
/**
 * $sAttCode should be a valid field code of the UserRequest class of type Integer or Decimal
 * $iIncrement must be an integer
 */
          ]]></comment>
          <code><![CDATA[
public function IncrementCounter($sAttCode, $iIncrement=1)
{
   // Defensive programming, ensure that the field code is valid on current class       
   if (MetaModel::IsValidAttCode(get_class($this), $sAttCode))
   {
       $iNew = $this->Get($sAttCode) + $iIncrement;
       $this->Set($sAttCode, $iNew);
   }
   return true;
}         
          ]]></ code> <!-- remove the blank between </ and code (wiki limitation) -->
        </method>
      </methods>
    </class>
  </classes>
</itop_design>

Some details on how to decode:

When you define one of the DBObject overwritable methods, be aware that it may have been done already within the standard iTop datamodel. If it is the case, at setup/toolkit compilation, as you add the method with a _delta=“define” it will fails if it exists already. In that case, you can do a “redefine”, but then mirror the existing code or you will break the current behavior of iTop.

arguments tags are required if:

• your extension will be loaded in the ITSM Designer
• AND the method must be called by an action on a transition

itop_design / classes / class@UserRequest / methods

        <method id="IncrementCounter" _delta="define">
          < ... >
          <arguments>
            <argument id="1">
              <mandatory>true</mandatory>
              <type>attcode</type>
            </argument>
            <argument id="2">
              <mandatory>false</mandatory>
              <type>int</type>
            </argument>
          </arguments>
        </method>

The easiest is to put this code into the file main.my-extension.php of your extension.

But it can also be put in the XML structure under:

itop_design / snippets

    <snippet id="ScheduledStart" _delta="define">
      <placement>module</placement>
      <module>itop-request-mgmt</module>
      <rank>200</rank>
      <content><![CDATA[
         /* enter here the code with class definition and methods */
      ]]></content>
    </snippet>