向服务器类添加新字段

本文档逐步说明了如何创建自己的iTop模块，以便向现有iTop对象添加新字段。

教程的目标

在本分步教程中，您将学习：

• 为iTop 2.0创建自己的扩展模块
• 向现有的对象类添加新字段

出于此教程的目的，我们将在“服务器 对象。

您将需要什么

• 将iTop安装在开发机器上，您可以在其上轻松地访问编辑文件。
• 一个文本编辑器，能够编辑PHP和XML文件并支持U-8。在Windows上，您可以使用写字板（记事本不喜欢Unix行结尾）或出色的免费开发IDE之一，例如PSPad 要么记事本++.

定制流程

定制流程如下：

1. 安装iTop的开发实例。最好不要在生产中进行试验！
2. 安装工具包 协助您进行定制
3. 使用以下命令创建一个新的（空）模块模块创建向导 
4. 将此新模块复制到iTop上的扩展文件夹中，然后再次运行安装程序以安装空模块
5. 修改扩展中的模块并使用工具包检查您的自定义

重复最后一点，直到对自定义满意为止。完成后，就可以部署新模块了。将模块文件夹复制到生产iTop实例的扩展目录中，然后运行安装程序进行安装。

循序渐进教程

创建您的自定义模块

使用模块创建向导。用以下值填充表单：

单击生成！将空模块下载为zip文件。

当模块修改现有类时，必须在声明要修改该类的模块之后加载它。为此，请确保新模块的依赖项中列出了第一个模块。

例如，如果要更改VirtualMachine类的定义，则自定义模块必须依赖于itop-virtualization-mgmtt2.0.0

安装空模块

将zip的内容扩展到开发iTop实例的扩展文件夹中。现在，您应该在扩展文件夹中有一个名为sample-add-attribute的文件夹。此文件夹包含以下文件：

• datamodel.sample-add-attribute.xml
• module.sample-add-attribute.php
• en.dict.sample-add-attribute.php
• model.sample-add-attribute.php

确保Web服务器的文件conf/production/config-itop.php是可写的（在Windows上：右键单击以显示文件属性，并取消选中只读标志；在Linux变更上为文件的权利），然后通过以下方式启动iTop安装：将您的浏览器指向http ::: your_itop/setupp

单击“继续»”开始重新安装。

在单击“下一步»”之前，请确保已选择“更新现有实例”。

继续执行向导的下一步……

您的自定义模块应出现在“扩展”列表中。如果不是这种情况，请检查是否在正确的位置复制了模块文件，并且Web服务器具有足够的权利可以读取它们。

在单击“下一步»”之前，请选择您的自定义模块并完成安装。

向服务器类添加新字段

使用常用文本编辑器，打开文件datamodel.sample-add-attribute.xml.

删除标签<menus> << menus>，因为该模块将不包含任何菜单定义。

在标签类中，添加以下代码：

 <class id="Server">
      <fields>
        <field id="notes" xsi:type="AttributeText" _delta="define">
          <sql>notes</sql>
          <default_value/>
          <is_null_allowed>true</is_null_allowed>
        </field>
      </fields>
     </class>

这指示iTop通过添加类型为AttributeText的新字段（请注意标签字段上的_delta =“ define”）来修改现有类“服务器”。这个新字段被命名为notes（因为它是使用id =“ notes”定义的）。相应的值将存储在数据库的注释栏中（由于定义<sql> notes << sql>）。

有关标签字段各种参数含义的更多信息（以及所有可能类型的字段的列表），请参考XML引用文档.

现在，您应该具有以下XML文件：

datamodel.sample-add-attribute.xml

 

<?xml version="1.0" encoding="UTF-8"?>
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
  <classes>
    <class id="Server">
      <fields>
        <field id="notes" xsi:type="AttributeText" _delta="define">
          <sql>notes</sql>
          <default_value/>
          <is_null_allowed>true</is_null_allowed>
        </field>
      </fields>
     </class>
  </classes>
</itop_design>

通过运行工具包检查您的修改。将浏览器指向http://your_itop/toolkit.

如果在此阶段报告了错误，请通过编辑XML文件来修复它们，然后通过单击工具包页面中的“刷新”按钮再次检查您的修改。

解决所有错误之后，可以使用工具包的第二个选项卡将修改应用于iTop：

单击按钮将iTop代码更新为：

1. 将XML数据模型编译为PHP类
2. 更新数据库架构以添加新的文本列。

此时，如果您查看MySQL数据库的架构，则可以看到添加到“服务器”表中的其他“注释”列。但是，如果您导航到iTop中的服务器，则没有任何改变。

这是因为没有指示iTop如何显示添加的字段。因此，该字段存在，但未在iTop中显示。

使新字段可见

让我们将新字段添加到服务器对象的“详细信息”中，就在“说明”下方。这可以通过重新定义服务器的“详细信息”的显示方式来实现。

使用文本编辑器打开文件datamodels/2.xxitop-config-mgmt/datamodel.itop-config-mgmt.xml。

搜索用于字符串<class id =“Server”，以定位服务器类的定义。

向下滚动到<presentation>标签，然后复制<details>…</ details>标签的全部内容。

将整个定义粘贴在结束</ field>标签之后的datamodel.sample-add-属性。xml中，并将其包含在<presentation>…</ presentation>标记中。

变更将标签的<details>打开为<details _delta =“ redefine”>，以指示iTop重新定义表示形式的“详细信息”。

插入3行：

                    <item id="notes">
                      <rank>40</rank>
                    </item>

在行之后：

                    <item id="description">
                      <rank>30</rank>
                    </item>

现在，您应该获取以下XML文件：

datamodel.sample-add-attribute.xml

 

<?xml version="1.0" encoding="UTF-8"?>
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
  <classes>
    <class id="Server">
      <fields>
        <field id="notes" xsi:type="AttributeText" _delta="define">
          <sql>notes</sql>
          <default_value/>
          <is_null_allowed>true</is_null_allowed>
        </field>
      </fields>
      <presentation>
        <details _delta="redefine">
          <items>
            <item id="softwares_list">
              <rank>10</rank>
            </item>
            <item id="contacts_list">
              <rank>20</rank>
            </item>
            <item id="documents_list">
              <rank>30</rank>
            </item>
            <item id="tickets_list">
              <rank>40</rank>
            </item>
            <item id="physicalinterface_list">
              <rank>50</rank>
            </item>
            <item id="fiberinterfacelist_list">
              <rank>60</rank>
            </item>
            <item id="networkdevice_list">
              <rank>70</rank>
            </item>
            <item id="san_list">
              <rank>80</rank>
            </item>
            <item id="logicalvolumes_list">
              <rank>90</rank>
            </item>
            <item id="providercontracts_list">
              <rank>100</rank>
            </item>
            <item id="services_list">
              <rank>110</rank>
            </item>
            <item id="col:col1">
              <rank>120</rank>
              <items>
                <item id="fieldset:Server:baseinfo">
                  <rank>10</rank>
                  <items>
                    <item id="name">
                      <rank>10</rank>
                    </item>
                    <item id="org_id">
                      <rank>20</rank>
                    </item>
                    <item id="status">
                      <rank>30</rank>
                    </item>
                    <item id="business_criticity">
                      <rank>40</rank>
                    </item>
                    <item id="location_id">
                      <rank>50</rank>
                    </item>
                    <item id="rack_id">
                      <rank>60</rank>
                    </item>
                    <item id="enclosure_id">
                      <rank>70</rank>
                    </item>
                  </items>
                </item>
                <item id="fieldset:Server:moreinfo">
                  <rank>20</rank>
                  <items>
                    <item id="brand_id">
                      <rank>10</rank>
                    </item>
                    <item id="model_id">
                      <rank>20</rank>
                    </item>
                    <item id="osfamily_id">
                      <rank>30</rank>
                    </item>
                    <item id="osversion_id">
                      <rank>40</rank>
                    </item>
                    <item id="oslicence_id">
                      <rank>50</rank>
                    </item>
                    <item id="cpu">
                      <rank>60</rank>
                    </item>
                    <item id="ram">
                      <rank>70</rank>
                    </item>
                    <item id="nb_u">
                      <rank>80</rank>
                    </item>
                    <item id="serialnumber">
                      <rank>90</rank>
                    </item>
                    <item id="asset_number">
                      <rank>100</rank>
                    </item>
                  </items>
                </item>
              </items>
            </item>
            <item id="col:col2">
              <rank>130</rank>
              <items>
                <item id="fieldset:Server:Date">
                  <rank>10</rank>
                  <items>
                    <item id="move2production">
                      <rank>10</rank>
                    </item>
                    <item id="purchase_date">
                      <rank>20</rank>
                    </item>
                    <item id="end_of_warranty">
                      <rank>30</rank>
                    </item>
                  </items>
                </item>
                <item id="fieldset:Server:otherinfo">
                  <rank>20</rank>
                  <items>
                    <item id="powerA_id">
                      <rank>10</rank>
                    </item>
                    <item id="powerB_id">
                      <rank>20</rank>
                    </item>
                    <item id="description">
                      <rank>30</rank>
                    </item>
                    <item id="notes">
                      <rank>40</rank>
                    </item>
                  </items>
                </item>
              </items>
            </item>
          </items>
        </details>
      </presentation>
    </class>
  </classes>
</itop_design>

通过运行工具包检查您的修改。将浏览器指向http://your_itop/toolkit.

如果在此阶段报告了任何错误，请通过编辑XML文件进行修复，然后单击工具包页面中的“刷新”按钮再次检查您的修改。

解决所有错误之后，可以使用工具包的第二个选项卡将修改应用于iTop：

如果现在在iTop中导航到服务器的详细信息，则应看到以下内容：

为新字段添加标签

请注意，新字段的标签为iTop is notes（默认情况下，它等于字段名称）。为了变更到附加注释，我们必须在字典中添加一个条目。

使用文本编辑器打开文件en.dict.sample-add-attribute.php。

插入行：

 'Class:Server/Attribute:notes' => 'Additional Notes',

在评论下方：

  字典条目去这里

您应该获取以下文件：

en.dict.sample-add-attribute.php

 

<?php
/**
 * Localized data
 *
 * @copyright   Copyright (C) 2013 Your Company
 * @license     http://opensource.org/licenses/AGPL-3.0
 */
 
Dict::Add('EN US', 'English', 'English', (
        // Dictionary entries go here
        'Class:Server/Attribute:notes' => 'Additional Notes',
));
?>

再过一次，运行工具包检查您的修改。

如果在此阶段报告了错误，请通过编辑PHP文件进行修复，然后单击工具包页面上的“刷新”按钮再次检查您的修改。

解决所有错误之后，可以使用工具包的第二个选项卡将修改应用于iTop：

如果在iTop中导航到服务器的详细信息，现在应该看到以下内容：

最终定制模块

定制的最终结果可在以下zip文件中找到：

sample-add-attribute.zip

下一步

您可以使用同一流程将更多字段添加到同一对象，或更改iTop中的其他对象。

如果希望添加的字段在修改后的对象类的默认“列表”视图或“搜索”表单中显示，则还必须重新定义相应的“表示”列表。

要将定制部署到另一个iTop服务器，只需将文件夹“ sample-add-attribute”复制到iTop的扩展文件夹，然后再次运行安装程序。

原贴链接：https://www.itophub.io/wiki/page?id=2_5_0%3Acustomization%3Aadd-attribute-sample

Adding a new field to the Server class

This document explains, step by step, how to create your own iTop module in order to add a new field to an existing iTop object.

Goals of this tutorial

In this step-by-step tutorial you will learn to:

• create your own extension module for iTop 2.0

• add a new field to an existing class of object

For the purpose of this tutorial we will add a text field labeled Additional Notes to the Server object.

What you will need

• iTop installed on a development machine, on which you can easily access/edit the files.

• A text editor capable of editing PHP and XML file and supporting UTF-8. On Windows you can use Wordpad (Notepad does not like Unix line endings) or one of the excellent free development IDEs like PSPad or Notepad++.

Customization process

The customization process is the following:

1. Install a development instance of iTop. It is always better not to experiment in production !!

2. Install the toolkit to assist you in the customization

3. Create a new (empty) module using the module creation wizard

4. Copy this new module in the extensions folder on iTop and run the setup again to install the empty module

5. Modify the module in extensions and use the toolkit to check your customizations

Repeat the last point until you are satisfied with your customization. When you are done, your new module is ready to be deployed. Copy the module folder in the extension directory on your production iTop instance and run the setup to install it.

Step by step tutorial

Create your customization module

Use the module creation wizard. Fill the form with the following values:

Click Generate ! to download the empty module as a zip file.

When a module modifies an existing class, it must be loaded after the module that declared the class to be modified. To achieve this, make sure that the first module is listed in the dependenciesof your new module.

For example if you want to alter the definition of the VirtualMachine class, your custom module must depend on itop-virtualization-mgmt/2.0.0

Install the empty module

Expand the content of the zip into the extensions folder of your development iTop instance. You should now have a folder named sample-add-attribute inside the extensions folder. this folder contains the following files:

• datamodel.sample-add-attribute.xml

• module.sample-add-attribute.php

• en.dict.sample-add-attribute.php

• model.sample-add-attribute.php

Make sure that the file conf/production/config-itop.php is writable for the web server (on Windows: right click to display the file properties and uncheck the read-only flag; on Linux change the rights of the file), then launch the iTop installation by pointing your browser to http://your_itop/setup/

Click “Continue »” to start the re-installation.

Make sure that “Update an existing instance” is selected before clicking “Next »”.

Continue to the next steps of the wizard…

Your custom module should appear in the list of “Extensions”. If it's not the case, check that the module files were copied in the proper location and that the web server has enough rights to read them.

Select your custom module before clicking “Next »” and complete the installation.

Add a new field to the Server class

Using you favorite text editor, open the file datamodel.sample-add-attribute.xml.

Remove the tags <menus></menus> since the module will not contain any menu definition.

Inside the classes tag, add the following piece of code:

    <class id="Server">
      <fields>
        <field id="notes" xsi:type="AttributeText" _delta="define">
          <sql>notes</sql>
          <default_value/>
          <is_null_allowed>true</is_null_allowed>
        </field>
      </fields>
     </class>

This instructs iTop to modify the existing class “Server” by adding a new field (notice the _delta=“define” on the field tag) of type AttributeText. This new field is named notes (since it is defined with id=“notes”). The corresponding values will be stored in the database in the column notes (thanks to the definition <sql>notes</sql>).

For more information about the meaning of the various parameters of the field tag (and also for the list of all possible types of fields) refer to the XML reference documentation.

You should now have the following XML file:

datamodel.sample-add-attribute.xml

 

<?xml version="1.0" encoding="UTF-8"?>
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
  <classes>
    <class id="Server">
      <fields>
        <field id="notes" xsi:type="AttributeText" _delta="define">
          <sql>notes</sql>
          <default_value/>
          <is_null_allowed>true</is_null_allowed>
        </field>
      </fields>
     </class>
  </classes>
</itop_design>

Check your modification by running the toolkit. Point your browser to http://your_itop/toolkit.

If any error is reported at this stage, fix them by editing the XML file and check again your modifications by clicking on the “Refresh” button in the toolkit page.

Once all the errors have been fixed, you can apply the modifications to iTop by using the second tab of the toolkit:

Click on the button Update iTop Code to:

1. Compile the XML data model to PHP classes

2. Update the database schema to add the new text column.

At this point, if you look at the schema of the MySQL database, you can see the additional “notes” column added to the “server” table. However if you navigate to a Server in iTop, nothing has changed.

This is because iTop was not instructed how to display the added field. So the field exists but is not displayed in iTop.

Make the new field visible

Let's add the new field to the “details” of the Server object, just below the “Description”. This can be achieved by redefining the way the “details” of a Server are displayed.

Using your text editor, open the file datamodels/2.x/itop-config-mgmt/datamodel.itop-config-mgmt.xml.

Search for the string <class id="Server" to locate the definition of the Server class.

Scroll down to the <presentation> tag and copy the whole content of the <details>…</details> tag.

Paste this whole definition in datamodel.sample-add-attribute.xml after the closing </field> tag, and enclose it in <presentation>…</presentation> tags.

Change the opening tag <details> to <details _delta=“redefine”> in order to instruct iTop to redefine the presentation for the “details”.

Insert the 3 lines:

                    <item id="notes">
                      <rank>40</rank>
                    </item>

Just after the lines:

                    <item id="description">
                      <rank>30</rank>
                    </item>

You should now obtain the following XML file:

datamodel.sample-add-attribute.xml

 

<?xml version="1.0" encoding="UTF-8"?>
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
  <classes>
    <class id="Server">
      <fields>
        <field id="notes" xsi:type="AttributeText" _delta="define">
          <sql>notes</sql>
          <default_value/>
          <is_null_allowed>true</is_null_allowed>
        </field>
      </fields>
      <presentation>
        <details _delta="redefine">
          <items>
            <item id="softwares_list">
              <rank>10</rank>
            </item>
            <item id="contacts_list">
              <rank>20</rank>
            </item>
            <item id="documents_list">
              <rank>30</rank>
            </item>
            <item id="tickets_list">
              <rank>40</rank>
            </item>
            <item id="physicalinterface_list">
              <rank>50</rank>
            </item>
            <item id="fiberinterfacelist_list">
              <rank>60</rank>
            </item>
            <item id="networkdevice_list">
              <rank>70</rank>
            </item>
            <item id="san_list">
              <rank>80</rank>
            </item>
            <item id="logicalvolumes_list">
              <rank>90</rank>
            </item>
            <item id="providercontracts_list">
              <rank>100</rank>
            </item>
            <item id="services_list">
              <rank>110</rank>
            </item>
            <item id="col:col1">
              <rank>120</rank>
              <items>
                <item id="fieldset:Server:baseinfo">
                  <rank>10</rank>
                  <items>
                    <item id="name">
                      <rank>10</rank>
                    </item>
                    <item id="org_id">
                      <rank>20</rank>
                    </item>
                    <item id="status">
                      <rank>30</rank>
                    </item>
                    <item id="business_criticity">
                      <rank>40</rank>
                    </item>
                    <item id="location_id">
                      <rank>50</rank>
                    </item>
                    <item id="rack_id">
                      <rank>60</rank>
                    </item>
                    <item id="enclosure_id">
                      <rank>70</rank>
                    </item>
                  </items>
                </item>
                <item id="fieldset:Server:moreinfo">
                  <rank>20</rank>
                  <items>
                    <item id="brand_id">
                      <rank>10</rank>
                    </item>
                    <item id="model_id">
                      <rank>20</rank>
                    </item>
                    <item id="osfamily_id">
                      <rank>30</rank>
                    </item>
                    <item id="osversion_id">
                      <rank>40</rank>
                    </item>
                    <item id="oslicence_id">
                      <rank>50</rank>
                    </item>
                    <item id="cpu">
                      <rank>60</rank>
                    </item>
                    <item id="ram">
                      <rank>70</rank>
                    </item>
                    <item id="nb_u">
                      <rank>80</rank>
                    </item>
                    <item id="serialnumber">
                      <rank>90</rank>
                    </item>
                    <item id="asset_number">
                      <rank>100</rank>
                    </item>
                  </items>
                </item>
              </items>
            </item>
            <item id="col:col2">
              <rank>130</rank>
              <items>
                <item id="fieldset:Server:Date">
                  <rank>10</rank>
                  <items>
                    <item id="move2production">
                      <rank>10</rank>
                    </item>
                    <item id="purchase_date">
                      <rank>20</rank>
                    </item>
                    <item id="end_of_warranty">
                      <rank>30</rank>
                    </item>
                  </items>
                </item>
                <item id="fieldset:Server:otherinfo">
                  <rank>20</rank>
                  <items>
                    <item id="powerA_id">
                      <rank>10</rank>
                    </item>
                    <item id="powerB_id">
                      <rank>20</rank>
                    </item>
                    <item id="description">
                      <rank>30</rank>
                    </item>
                    <item id="notes">
                      <rank>40</rank>
                    </item>
                  </items>
                </item>
              </items>
            </item>
          </items>
        </details>
      </presentation>
    </class>
  </classes>
</itop_design>

Check your modification by running the toolkit. Point your browser to http://your_itop/toolkit.

If any error is reported at this stage, fix it by editing the XML file and check again your modifications by clicking on the “Refresh” button in the toolkit page.

Once all the errors have been fixed, you can apply the modifications to iTop by using the second tab of the toolkit:

If you now navigate to the details of a Server in iTop you should see the following:

Add a label for the new field

Notice that the label of the new field is iTop is notes (by default it is equal to the name of the field). In order to change this to Additional Notes we have to add an entry in the dictionary.

Using you text editor, open the file en.dict.sample-add-attribute.php.

Insert the line:

  'Class:Server/Attribute:notes' => 'Additional Notes',

Just below the comment:

  // Dictionary entries go here

You should obtain the following file:

en.dict.sample-add-attribute.php

 

<?php
/**
 * Localized data
 *
 * @copyright   Copyright (C) 2013 Your Company
 * @license     http://opensource.org/licenses/AGPL-3.0
 */
 
Dict::Add('EN US', 'English', 'English', (
        // Dictionary entries go here
        'Class:Server/Attribute:notes' => 'Additional Notes',
));
?>

One more time, check your modification by running the toolkit.

If errors are reported at this stage, fix them by editing the PHP file and check again your modifications by clicking on the “Refresh” button in the toolkit page.

Once all the errors have been fixed, you can apply the modifications to iTop by using the second tab of the toolkit:

If you navigate to the details of a Server in iTop, you should now see the following:

Final Customization Module

The final result of the customization is available in the zip file below:

sample-add-attribute.zip

Next Steps

You can use the same process to add more fields to the same object, or to alter other objects in iTop.

If you want the added fields to appear either in the default “list” view or “search” form for the modified class of objects, the corresponding “presentation” list must be redefined as well.

To deploy your customization to another iTop server, simply copy the folder “sample-add-attribute” to the extensions folder of iTop and run the setup again.