iTop定制

2.x工具包可在此处获得:iTopDataModelToolkit-2.3.zip

iTop建立在ORM(对象Relational Mapper)抽象层之上,该抽象层依赖于由PHP类组成的“ Meta数据模型”的定义。从iTop 2.0开始,可以用XML描述Meta数据模型,然后在设置应用时将其“编译”为PHP类。

iTop架构可以描述为以下架构:

iTop 2.0 Architecture

上面模式中的橙色框是应用的一部分,可以自定义。

定制类型意思文献资料目标听众
扩展或修改数据模型并调整控制台的行为XML文件XML引用iTop顾问,ITIL专家
通过插件扩展通用用户接口PHP文件扩展APIPHP开发人员
创建新的用户界面页面以实施新的Web服务,专门的导出或面向特定任务的用户界面PHP文件ORM APIPHP开发人员
创建自己的安全方案PHP文件用户权利APIPHP开发人员
变更,客户,门户或开发新的门户XML文件自定义客户门户iTop顾问,ITIL专家,Web设计师,PHP开发人员

从iTop 2.0开始,可以通过编写简单的XML文件(仅包含与标准数据模型的差异)​​来对meta数据模型进行修改。这样一来,您所做的修改将保存在一个单独的文件中,该文件将继续适用于iTop的下一个数据模型,因此在使用升级时保留您的自定义内容。

了解iTop文件结构

iTop文件和文件夹的布局可以如下所示:

iTop 2.0 files layout

以下文件夹在iTop中有特殊用途:

conf:包含配置文件,每个环境带有一个子文件夹(请参阅下面的环境)。

data:包含应用生成的数据,如对象生命周期的图像(如果系统上有graphviz)

datamodels:包含元数据模型定义,每个iTop主要版本都有一个子文件夹。

env-xxxx:这些文件夹(每个环境)包含“已编译”数据模型。每次重新安装或升级应用时,都会完全重新创建env-production文件夹。如果您编辑其内容,请注意,重新安装或升级后所做的修改将丢失。

extensions:该文件夹是复制不属于iTop的标准发行版的扩展模块的地方。

log:包含应用的日志文件:setup.log和 error.log

所有其他文件夹应被视为应用的源代码的一部分,通常不应进行修改。应用永远不会写入这些文件夹,对于应用流程,它们可以被标记为只读。

环境环境

iTop 2.0引入了一个新概念,即“环境”的概念。环境是iTop的实例,它运行相同的代码库,但可能具有自己的环境和配置文件。环境由以下材料制成:

存储在conf/name_of_the_environment/config-itop.php中的配置文件。

数据模型运行时,存储在env-name_of_the_环境中

如果两个不同的环境的配置文件表明是这样,则它们可以在同一数据库上运行。

工具包自动创建一个单独的环境(名为工具包),以编译XML数据模型和工具包及其一致性,而不会影响“生产”环境。当更改确定时,您可以指示工具包将经过验证的更改应用于“生产”环境。

扩展与模块

模组

iTop中数据模型定义的基本单位称为模块。 iTop的流程安装将每个模块作为一个整体来考虑。

一个模块将交付给定特性所需的所有文件组合在一起:XML,PHP类,Javascript和CSS文件,PHP页面,图像等中的数据模型定义。一个模块至少包含一个文件:模块定义文件,始终命名为module.name_of_the_module.php。

尽管您始终可以补丁源代码,但是自定义iTop的最佳方法是编写自己的模块。这将创建干净的自定义包装,并允许为部署或升级轻松(重新)安装。

扩展

扩展的概念是在iTop 2.4中引入的。扩展是一个或多个模块的组合。在安装过程中建议给终端用户的安装选项是基于iTop的“扩展”文件夹中的扩展进行的。为了向后兼容,如果在扩展之外找到模块,则该模块将直接列为安装选项。

扩展由每个扩展名的根文件夹中的extension.xml文件标识。

当一个扩展由一个模块构成时,预期的结构是一个文件夹,其中所有文件extension.xml,module.xxxx.php,datamodel.xxxx.xml等都处于同一级别。

当扩展由多个模块组成时,预期的结构是一个仅包含extension.xml文件的单个根文件夹,每个模块具有一个子文件夹(具有module.xxxx.php,datamodel.xxxx.xml等)

如果多个扩展包含同一模块(由其代码标识),则安装流程将仅安装该模块的一个副本:最高的版本。

PHP与XML数据模型的定义

在iTop版本1.x中,数据模型定义被编写为纯PHP类。 iTop版本2.0支持数据模型的PHP和XML定义。

XML定义比PHP定义具有一个主要优势:一个模块中的XML定义可以更改另一个模块中定义的数据模型。例如,可以创建扩展模块,该扩展模块将在安装时将属性添加到标准iTop数据模型中定义的类“服务器”。扩展模块不需要替换整个“ itop-config-数据模型”模块(定义了服务器类的模块),它只需更改其他地方定义的类的定义即可。

为了在PHP中获得相同的效果,唯一的解决方案是克隆整个itop-config-mgmt模块,并将其替换为您自己修补的版本。当发布模块的新版本时,您必须重做此差异,并且补丁再次工作以生成您自己的模块的新版本。由于XML定义直接定义为差异,因此版本是自动的。

模块内容

如果my-module是模块的名称,则模块文件夹将包含以下文件:

文档名称描述
extension. xmliTop 2.4中的新增功能:XML定义文件,由iTop 2.4及更高版本使用。该文件包含一些与模块PHP文件类似的信息,但是启用了对包含多个模块的扩展的支持。如果模块位于已经包含extension.xml文件的文件夹中(位于父文件夹中),则该文件的内容将被忽略。
module.my-module.php模块定义文件。必选包含模块(名称版本,对其他模块的依赖关系等)及其组件的说明。
datamodel.my-module.xmlXML中的数据模型。安装后,“编译”将基于XML定义生成模型。xxxxx.php文件。 XML文件可以包含类,菜单和简档(角色)的定义
model.my-module.php如果选择直接在PHP中定义数据模型,则该文件是放置此类定义的地方
main.my-module.phpPHP代码和实用程序。对于某些包含大量PHP代码的模块,提取PHP代码并在此单独的文件中对其进行编辑比将代码嵌入XML中要容易得多。
images将图像(类图标等)存储在自己的子文件夹中是一个很好的实践
en.dict.my-module.php字典文件,如果需要一些本地化的字符串

以itop-开头的模块名称保留给iTop软件包中的官方模块使用。为避免与其他扩展命名冲突,建议使用以公司名称开头的名称来命名自定义模块。例如,由Combodo开发的自定义模块被命名为combodo-xxxx。

处理本地化

所有字符串应包含在词典文件中。

请参阅专用的Wiki页面: 如何翻译

创建一个模块

填写下面的表单,然后单击“生成”以生成一个空模块作为自定义的起点:

窗体顶端

模块名称:sample-module(必须唯一。以“ itop-”和“ combodo-”开头的名称保留供Combodo使用)
模块标签:Sample Module(在设置过程中显示)
模块版本:1.0.0 
类别:business 
依存关系: (以逗号分隔的模块名称版本列表)

查找依赖项

当您的模块更改由另一个模块定义的类时,该模块必须首先在安装和工具包 XML 编译中存在并处理,这将执行 PHP 代码生成。

XML 数据模型树是一步一步构建的,一个又一个地添加模块,因此,如果树中尚不存在该标记,则具有 _delta="重新定义"指令的 XML 标记将失败。

  1. 首先在"数据模型/2.x/"<my-itop>模块中搜索要更改或嫁接到的标记。您的模块将依赖于找到的模块。
  2. 然后检索您依赖的模块:文件模块中的名称和版本.php。对于作为 iTop 社区的一部分的模块,模块版本遵循主要 iTop 版本

安装工具包

  • 下载工具包压缩文件: iTopDataModelToolkit-2.3.zip
  • 展开zip文件的内容,以在开发iTop实例的根目录中创建目录“工具包”。
  • 将浏览器指向http://<your_itop>/toolkit

开发工作流程

  • 创建一个空模块
  • 安装iTop的开发实例,包括“扩展”文件夹中的空模块
  • 在开发实例上安装工具包
  • 编辑扩展模块并使用工具包进行验证
  • 将对扩展模块所做的更改应用于“生产”环境
  • 测试带有一些示例数据的模块。万一遇到麻烦,请在第4点进行迭代来修复它们。

每次修改数据模型XML文件时,都必须将它们“编译”为PHP文件,这是工具包的工作。但是,模块中的所有其他文件都只是从“ extension/your_module”文件夹复制到“ env-production/your_module”文件夹。为了加快在Linux系统上的调试速度,您可以通过指向其实际源文件的符号链接来替换这些文件。因此,对源的任何修改在iTop中都立即生效,您只需单击浏览器的刷新按钮即可。

扩展完成后,可以通过以下方式将其部署在生产系统上:

将包含扩展模块的文件夹复制到生产系统上的“扩展”文件夹

将配置文件标记为read/write

再次运行安装程序,然后在交互式安装程序结尾的“扩展”列表中选择您的模块

使用工具包

安装工具包后,将浏览器指向:http://<your_itop>/toolkit.

第一个选项卡执行一些基本的一致性检查和数据模型定义的验证。每次更改数据模型的定义时,您都可以使用“刷新”按钮再次执行验证。在此选项卡中执行的检查适用于特定的“数据模型”验证,因此对使用“生产”验证的实际iTop实例没有影响。

Customization toolkit - page 1

XML文件的加载顺序很重要(特别是如果XML文件更改了另一个文件中给出的定义)。该加载顺序遵循模块描述文件中声明的“依赖关系”。

如果您得到如下的错误:

XML数据模型加载器:找不到类别XXXX的节点

这可能意味着您的模块在定义了类XXXX的模块上缺少依赖。

安装程序运行时,将计算加载顺序,并将生成的顺序写入配置文件。请注意,工具包不会重新计算此加载顺序。因此,如果您错过了依赖,则需要修改模块定义文件以添加此依赖,然后再次运行安装程序以重新计算整个配置文件。

当第一个选项卡不显示任何错误时,可以移至第二个选项卡以:

检查变更到数据库架构

通过单击“ Udpate iTop Code”将数据库架构和数据模型定义的更改应用于“生产” iTop环境。

Customization toolkit - page 2

工具包的第三个选项卡可用于更新数据同步源(如果有任何受数据模型更改影响的同步源),并检查内部数据中是否存在用于层次结构键的任何差异。此选项卡直接在“生产”环境上运行。

Customization toolkit - page 3

生命周期图像

对象生命周期的图形表示显示在iTop的“数据模型”页面中(选项卡“生命周期”)。如果您修改了对象的生命周期,则需要在Web服务器上安装Graphviz才能重新计算此图像。看到安装iTop有关安装Graphviz的更多信息。

原文:https://www.itophub.io/wiki/page?id=2_6_0%3Acustomization%3Adatamodel


iTop Customization

The 2.x toolkit is available here: iTopDataModelToolkit-2.3.zip

iTop is built on top of an ORM (Object Relational Mapper) abstraction layer that relies on the definition of a “Meta Data Model” made of PHP classes. Starting with iTop 2.0 the Meta Data Model can be described in XML which is then “compiled” into PHP classes during the setup of the application.

The iTop architecture can be depicted as the schema below:

iTop 2.0 Architecture

The orange boxes on the schema above are the parts of the application that can be customized.

Type of customizationMeanDocumentationIntended audience
Extending or modifying the data model and adjusting the behavior of the consoleXML filesXML referenceiTop consultants, ITIL specialists
Extending the generic user-interface via a plug-inPHP filesExtensions APIPHP developers
Creating new user interface pages to implement new web services, specialized exports or a specific task oriented user interfacePHP filesORM APIPHP developers
Creating your own security schemePHP filesUser Rights APIPHP developers
Change the customer portal or develop a new portalXML filesCustomize the Customer PortaliTop consultants, ITIL specialists, Web designers, PHP developpers

Starting with iTop 2.0, the modification of the meta data model can be done by writing a simple XML file that will contain only the differences with the standard data model. By doing so, your modifications are kept in a separate file, that will remain applicable to the next version of iTop.Thus preserving your customizations in case of upgrade.

Understanding the iTop file structure

The layout of the iTop files and folders can be depicted as below:

iTop 2.0 files layout

The following folders have a special usage in iTop:

  • conf: contains the configuration files, with one sub-folder per environment (see Environments below).

  • data: contains application generated data, like the image for the object life-cycle (if graphviz is available on the system)

  • datamodels: contains the meta data model definitions, with one sub-folder per major version of iTop.

  • env-xxxx: these folders (one per environment) contain the “compiled ” data model. The env-production folder is completely re-created each time the application is re-installed or upgraded. If you edit its content, be aware that your modifications will be lost upon re-install or upgrade.

  • extensions: this folder is the place where to copy extensions modules that are not part of the standard distribution of iTop.

  • log: contains the log files of the application: setup.log and error.log

All the other folders should be considered as part of the source code of the application and should generally not be modified. The application never writes to these folders, they can be marked as read-only for the web server process.

Environments

A new concept introduced by iTop 2.0 is the notion of “environment”. An environment is an instance of iTop running the same code base but with potentially its own data model and configuration file. An environment is made of:

  • A configuration file stored in conf/name_of_the_environment/config-itop.php.

  • A data model runtime, stored in env-name_of_the_environment

Two different environments can operate on the same database if their configuration files says so.

The toolkit automatically creates a separate environment (named toolkit) in order to compile the XML data model and test its consistency without affecting the “production” environment. When the changes are Ok, you can instruct the toolkit to apply the validated changes to the “production” environment.

Extensions versus Modules

Modules

The basic unit of data model definition in iTop is called a module. The installation process of iTop considers each module as a whole.

A module groups together all the files needed to deliver a given feature: data model definitions in XML, PHP classes, Javascript and CSS files, PHP pages, images, etc… A module contains at least one file: the module definition file, always named module.name_of_the_module.php.

Though you can always patch the source code, the best way to customize iTop consists in writing your own module. This creates a clean packaging of the customization and allow an easy (re)installation for your deployment or in case of upgrade.

Extensions

The concept of extension is introduced with iTop 2.4. An extension is an assembly of one or more module. The installation options proposed to the end-user during the setup are based on the extensions found in the “extensions” folder of iTop; For backward compatibility, if a module is found outside of an extension, this module will be directly listed as an installation option.

Extensions are identified by the extension.xml file found in the root folder of each extension.

When an extension is made of one single module, the expected structure is one single folder with all the files extension.xml, module.xxxx.php,datamodel.xxxx.xml, etc. at the same level.

When an extension is made of several modules, the expected structure is one single root folder containing only the extension.xml file, with one subfolder per module (with module.xxxx.php, datamodel.xxxx.xml, etc)

If several extensions contain the same module (identified by its code), the installation process will install only one copy of the module: the highest version.

PHP versus XML data model definitions

In iTop versions 1.x, the data model definition was written as a plain PHP classes. iTop version 2.0 support both PHP and XML definitions for the data model.

XML definitions have one major advantage over PHP definitions: the XML definition in one module can alter the data model defined in another module. For example, it is possible to create an extension module that will - when installed - add an attribute to the standard class “Server”, which is defined in the standard iTop data model. The extension module does not need to replace the whole “itop-config-management” module (where the Server class is defined), it can just alter the definition of a classe defines elsewhere.

In order to achieve the same effect in PHP, the only solution consists in cloning the whole itop-config-mgmt module and replacing it with your own patched version. When a new version of the module is released, you have to redo this diff & patch work again to produce a new version of your own module. Since an XML definition is directly defined as a difference, the upgrade is automatic.

Content of a module

If my-module is the name of your module, the module folder will contain the following files:

File NameDescription
extension.xmlNew in iTop 2.4: An XML definition file, used by iTop 2.4 and above. This file contains some information similar to the module PHP file, but enables the support of extensions containing several modules. If the module is located inside a folder already containing an extension.xml file (in the parent folder), the content of this file is ignored.
module.my-module.phpThe module definition file. Mandatory. Contains the description of the module (name version, dependencies on other modules, etc.) and its components.
datamodel.my-module.xmlData Model in XML. Upon installation the “compilation” will produce the model.xxxxx.php file based on the XML definitions. The XML file can contain the definition of classes, menus and profiles
model.my-module.phpIf you choose to define the data model directly in PHP, then this file is the place to put such definitions
main.my-module.phpPHP code and utilities. For some modules that contain a lot of PHP code, it is easier to extract the PHP code and edit it in this separate file than letting the code embedded in the XML.
imagesIt is a good practice to store the images (classes icons, etc…) in their own sub folder
en.dict.my-module.phpDictionnary file, if you need some localized strings

The module names starting with itop- are reserved for offical modules from the iTop package. To avoid naming conflicts with other extensions it is recommended to name your custom modules with a name starting with the name of your company. For example the custom modules developed by Combodo are named combodo-xxxx.

Handling localizations

All strings should be contained in dictionnary files.

Please see the dedicated wiki page : How to translate

Creating a module

Fill the form below and click on “Generate” to generate an empty module as the starting point for your customization:

Module Name: (must be unique. Names starting with "itop-" and "combodo-" are reserved for use by Combodo)
Module Label: (Displayed during the setup)
Module Version:  
Category:  
Dependencies: (comma separated list of module names/versions)
 
 

Installing the Toolkit

  • Download the toolkit zip file: iTopDataModelToolkit-2.3.zip

  • Expand the content of the zip file to create a directory “toolkit” at the root of the your development iTop instance.

  • Point your browser to http://<your_itop>/toolkit

Development Workflow

  1. Create an empty module

  2. Install a development instance of iTop, including your empty module in the “extensions” folder

  3. Install the toolkit on your developement instance

  4. Edit your extension module and validate it with the toolkit

  5. Apply the changes made to your extension module to the “production” environment

  6. Test your module with some sample data. In case of troubles, fix them by iterating at point 4.

The datamodel XML files must be “compiled” to PHP files each time you modify them, this is the job of the toolkit. However all other files in your module are simply copied from the “extension/your_module” folder to “env-production/your_module” folder. To speed-up the debugging on Linux systems you can replace these files by a symbolic link to their actual source file; Thus any modification to the source is immediately effective in iTop, you just have to hit the refresh button of the browser.

When your extension is completed you can deploy it on your production system by:

  1. Copying the folder containing your extension module to the “extensions” folder on the production system

  2. Marking the configuration file as read/write

  3. Running the setup again and selecting your module in the list of “extensions” at the end of the interactive setup

Using the Toolkit

Once the toolkit is installed, point your browser to: http://<your_itop>/toolkit.

The first tab performs some basic consistency checks and validation of the data model definition. You can use the “Refresh” button to perform the validation again each time the data model definition has changed. The checks performed in this tab work on the specific “toolkit” environment and thus have no effect on the actual iTop instance that uses the “production” environment.

Customization toolkit - page 1

The order in which the XML files are loaded is important (especially if an XML file alters the definitions given in another one). This loading order follows the “dependencies” declared in the module description file.

If you get an error like:

XML datamodel loader: could not find node for class/XXXX

This probably means that your module lacks a dependency on the module where the class XXXX is defined.

When the setup runs the loading order is computed and the resulting order is written in the configuration file. Be aware that the toolkit does not recompute this loading order. Therefore if you miss a dependency, you need to modify the module definition file to add this dependency and run the setup again in order to recompute the whole configuration file

When the first tab does not show any error, you can move to the second tab to:

  • check the change to the database schema

  • apply the changes of the database schema and data model definitions to the “production” iTop environment by clicking on “Udpate iTop Code”

Customization toolkit - page 2

The third tab of the toolkit can be used to update the Data Synchronization sources (if there are any that was impacted by the changes to the data model), and to check if there are any discrepencies in the internal data maintained for hierachical keys. This tab directly operates on the “production” environment.

Customization toolkit - page 3

Life-cycle images

A graphical representation of the object's life-cycle is displayed in the “Data Model” page of iTop (tab “Life-cycle”). If you modify an object's life-cycle, then you'll need to have Graphviz installed on the web server to get this images re-computed. See Installing iTop for more information about installing Graphviz.

标签:
由 superadmin 在 2020/08/27, 16:30 创建
    

需要帮助?

如果您需要有关XWiki的帮助,可以联系:

深圳市艾拓先锋企业管理咨询有限公司