You are browsing the documentation for iTop 3.0 which is not the current version.

Consider browsing to iTop 3.1 documentation

Syntax used in Tutorials

Add XML code

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.

Simplified syntax

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>

Full XML structure

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
If you use a _delta=“define” it's safer to set a _delta=“must_exist” somewhere above in the tree structure.

Test it

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.

Add PHP code

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.

Method on existing class

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

Simplified syntax

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

Full XML code

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:

Source should be translated into…
public function IncrementCounter() <access>public</access>
protected function … <access>protected</access>
public function … <static>false</static>
public static function … <static>true</static>
public function IncrementCounter( <method id=“IncrementCounter”>

Risks

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.

ITSM Designer specific

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>

Within a new PHP class

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> 
3_0_0/customization/insert-xml.txt · Last modified: 2022/01/21 16:52 (external edit)
Back to top
Contact us