iTopCN – 修改数据模型

Docs: n:n 自反与对称关系

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何创建类与自身的对称多对多关系。更多详细内容请参考 iTop 官方文档。

概述

创建类与自身的对称关系，例如人员的同事关系。若 John 是 Anna 的同事，则 Anna 也是 John 的同事。

iTop 默认的多对多关系不是对称的。本教程通过自动创建双向记录来实现对称性。

人员同事关系

核心思路

当用户创建 (src_person = John, dest_person = Anna) 时，后台自动创建其镜像 (src_person = Anna, dest_person = John)。

AfterInsert

public function AfterInsert()
{
 $oSearch = DBSearch::FromOQL('SELECT lnkPersonToPerson WHERE src_person_id = :src_id AND dest_person_id = :dest_id');
 $oSet = new DBObjectSet($oSearch, array(),
 array(
 'src_id' => $this->Get('dest_person_id'),
 'dest_id' => $this->Get('src_person_id'),
 ),
 );
 if ($oSet->Count() == 0) {
 $oLnk = MetaModel::NewObject("lnkPersonToPerson",
 array('src_person_id' => $this->Get('dest_person_id'),
 'dest_person_id' => $this->Get('src_person_id')));
 $oLnk->DBInsert();
 }
}

AfterUpdate

public function AfterUpdate()
{
 $aChanges = $this->ListPreviousValuesForUpdatedAttributes();
 $sPrevSrc = array_key_exists('src_person_id', $aChanges) ? $aChanges['src_person_id'] : $this->Get('src_person_id');
 $sPrevDest = array_key_exists('dest_person_id', $aChanges) ? $aChanges['dest_person_id'] : $this->Get('dest_person_id');

 $oSearch = DBSearch::FromOQL('SELECT lnkPersonToPerson WHERE src_person_id = :src_id AND dest_person_id = :dest_id');
 $oSet = new DBObjectSet($oSearch, array(),
 array(
 'src_id' => $sPrevDest,
 'dest_id' => $sPrevSrc,
 ),
 );
 if ($oSet->Count() > 0) {
 while($oLnk = $oSet->Fetch()) {
 $oLnk->Set('src_person_id', $this->Get('dest_person_id'));
 $oLnk->Set('dest_person_id', $this->Get('src_person_id'));
 $oLnk->DBUpdate();
 }
 } else {
 $oSearchNew = DBSearch::FromOQL('SELECT lnkPersonToPerson WHERE src_person_id = :src_id AND dest_person_id = :dest_id');
 $oSetNew = new DBObjectSet($oSearchNew, array(),
 array(
 'src_id' => $this->Get('dest_person_id'),
 'dest_id' => $this->Get('src_person_id'),
 ),
 );
 if ($oSetNew->Count() === 0) {
 $oLnk = MetaModel::NewObject("lnkPersonToPerson", array(
 'src_person_id' => $this->Get('dest_person_id'),
 'dest_person_id' => $this->Get('src_person_id'),
 ));
 $oLnk->DBInsert();
 }
 }
}

AfterDelete

public function AfterDelete()
{
 $oSearch = DBSearch::FromOQL('SELECT lnkPersonToPerson WHERE src_person_id = :src_id AND dest_person_id = :dest_id');
 $oSet = new DBObjectSet($oSearch, array(),
 array(
 'src_id' => $this->Get('dest_person_id'),
 'dest_id' => $this->Get('src_person_id'),
 ),
 );
 if ($oSet->Count() > 0) {
 while($oLnk = $oSet->Fetch()) {
 $oLnk->DBDelete();
 }
 }
}

NetworkDevice & ConnectableCI

此用例来自 iTop 默认数据模型，比上面的更复杂，因为有时对称有时不对称，取决于 ConnectableCI 是否也是 NetworkDevice。

AfterInsert

public function AfterInsert()
{
 $oDevice = MetaModel::GetObject('ConnectableCI', $this->Get('connectableci_id'));
 if (is_object($oDevice) && (get_class($oDevice) == 'NetworkDevice')) {
 $sOQL = "SELECT lnkConnectableCIToNetworkDevice
 WHERE connectableci_id = :device AND networkdevice_id = :network
 AND network_port = :nwport AND device_port = :devport";
 $oConnectionSet = new DBObjectSet(DBObjectSearch::FromOQL($sOQL),
 array(),
 array(
 'network' => $this->Get('connectableci_id'),
 'device' => $this->Get('networkdevice_id'),
 'devport' => $this->Get('network_port'),
 'nwport' => $this->Get('device_port'),
 )
 );
 if ($oConnectionSet->Count() == 0) {
 $sLink = $this->Get('connection_type');
 $sConnLink = ($sLink == 'uplink') ? 'downlink' : 'uplink';

 $oNewLink = new lnkConnectableCIToNetworkDevice();
 $oNewLink->Set('networkdevice_id', $this->Get('connectableci_id'));
 $oNewLink->Set('connectableci_id', $this->Get('networkdevice_id'));
 $oNewLink->Set('network_port', $this->Get('device_port'));
 $oNewLink->Set('device_port', $this->Get('network_port'));
 $oNewLink->Set('connection_type', $sConnLink);
 $oNewLink->DBInsert();
 }
 }
}

AfterDelete

public function AfterDelete()
{
 $oDevice = MetaModel::GetObject('ConnectableCI', $this->Get('connectableci_id'), false);
 if (is_object($oDevice) && (get_class($oDevice) == 'NetworkDevice')) {
 $sOQL = "SELECT lnkConnectableCIToNetworkDevice
 WHERE connectableci_id = :device AND networkdevice_id = :network
 AND network_port = :nwport AND device_port = :devport";
 $oConnectionSet = new DBObjectSet(DBObjectSearch::FromOQL($sOQL),
 array(),
 array(
 'network' => $this->Get('connectableci_id'),
 'device' => $this->Get('networkdevice_id'),
 'devport' => $this->Get('network_port'),
 'nwport' => $this->Get('device_port'),
 )
 );
 while ($oConnection = $oConnectionSet->Fetch()) {
 $oConnection->DBDelete();
 }
 }
}

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:n-n-reflexive-relation

版本：3_2_0/customization/n-n-reflexive-relation.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 创建新的 CI 类：Monitor

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何创建新的 iTop 模块以添加自定义 CI 类。以创建 Monitor（显示器）类为例。更多详细内容请参考 iTop 官方文档。

概述

本教程将创建一个新的 CI 类 Monitor，继承自 PhysicalDevice，并添加一个 technology 字段来区分 CRT 和 LCD 显示器。

使用 ITSM Designer（Combodo 客户）

Combodo 客户可直接在 ITSM Designer 中创建新类。

使用 iTop 扩展

创建模块

使用扩展创建向导：

标签	值	说明
模块名称	sample-add-class	以 `itop-` 和 `combodo-` 开头的名称保留
模块标签	Add Class Sample	安装向导中显示的标签
模块版本	1.0.0	使用 X.Y.Z 三位版本号
类别	business	修改数据模型的模块使用 ‘business’ 类别
依赖	itop-config-mgmt/2.0.0, itop-endusers-devices/2.0.0	依赖配置管理和终端用户设备模块

添加 Monitor 类

编辑 datamodel.sample-add-class.xml，在 <classes> 内添加：

<class id="Monitor" _delta="define">
 <parent>PhysicalDevice</parent>
 <properties>
 <category>bizmodel,searchable</category>
 <abstract>false</abstract>
 <key_type>autoincrement</key_type>
 <db_table>monitor</db_table>
 <db_key_field>id</db_key_field>
 <db_final_class_field/>
 <naming>
 <attributes>
 <attribute id="name"/>
 </attributes>
 </naming>
 <style>
 <icon>images/monitor.png</icon>
 </style>
 <reconciliation>
 <attributes>
 <attribute id="name"/>
 <attribute id="org_id"/>
 <attribute id="organization_name"/>
 </attributes>
 </reconciliation>
 </properties>
 <fields>
 <field id="technology" xsi:type="AttributeEnum">
 <values>
 <value>crt</value>
 <value>lcd</value>
 </values>
 <sql>technology</sql>
 <default_value/>
 <is_null_allowed>true</is_null_allowed>
 <display_style>radio_horizontal</display_style>
 </field>
 </fields>
 <presentation>
 <details>
 <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="brand_id"><rank>60</rank></item>
 <item id="model_id"><rank>70</rank></item>
 <item id="technology"><rank>75</rank></item>
 <item id="serialnumber"><rank>80</rank></item>
 <item id="asset_number"><rank>90</rank></item>
 <!-- ... 其他字段 ... -->
 </items>
 </details>
 <search><!-- ... --></search>
 <list><!-- ... --></list>
 </presentation>
</class>

添加类图标

在 extensions/sample-add-class/images/ 目录下放置 monitor.png 图标文件。

修复标签

编辑 en.dict.sample-add-class.php，添加字典条目：

Dict::Add('EN US', 'English', 'English', array(
 'Class:Monitor' => 'Monitor',
 'Class:Monitor+' => 'A computer display',
 'Class:Monitor/Attribute:technology' => 'Technology',
 'Class:Monitor/Attribute:technology+' => 'Technology used for the display',
 'Class:Monitor/Attribute:technology/Value:crt' => 'CRT',
 'Class:Monitor/Attribute:technology/Value:lcd' => 'LCD',
));

添加到 Model.type

将 Monitor 添加到 Model 类的 type 枚举值中：

<class id="Model" _delta="must_exist">
 <fields>
 <field id="type" xsi:type="AttributeEnum">
 <values>
 <value id="Monitor" _delta="define">Monitor</value>
 </values>
 </field>
 </fields>
</class>

添加仪表盘项

将 Monitor 添加到配置管理概览仪表盘的 “终端用户设备” 区域：

<menus>
 <menu id="ConfigManagementOverview" xsi:type="DashboardMenuNode" _delta="must_exist">
 <definition>
 <cells>
 <cell id="2" _delta="must_exist">
 <dashlets>
 <dashlet id="99" xsi:type="DashletBadge" _delta="define">
 <rank>8</rank>
 <class>Monitor</class>
 </dashlet>
 </dashlets>
 </cell>
 </cells>
 </definition>
 </menu>
</menus>

部署

将模块文件夹复制到目标 iTop 的 extensions 目录并运行安装。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:add-class-sample

版本：3_2_0/customization/add-class-sample.txt · Last modified: 2026/03/16 14:02 by 127.0.0.1

Docs: 创建新配置文件

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何创建新的 iTop 配置文件以控制用户访问权限。更多详细内容请参考 iTop 官方文档。

概述

本教程将创建两个新配置文件：

Read-Only Except Requests — 允许浏览所有对象，但只能创建/修改用户请求
Read-Only No Portal Access — 纯只读配置，允许浏览但禁止修改任何内容

使用 ITSM Designer（Combodo 客户）

创建新配置文件

导航到 User Rights Designer 标签页
点击工具栏中的创建按钮
为新配置文件添加组
为每个组定义权限：Allow（允许）、Undefined（未定义/不允许）、Denied（明确拒绝）

创建新组

若现有组不满足需求，可创建新组：

点击工具栏中的创建按钮
使用中心窗格的树状视图勾选要添加到组中的类

使用 iTop 扩展

创建模块

使用扩展创建向导：

标签	值	说明
模块名称	sample-add-profile	以 `itop-` 和 `combodo-` 开头的名称保留
模块标签	Add Profile Sample	安装向导中显示的标签
模块版本	1.0.0	使用 X.Y.Z 三位版本号
类别	business	修改数据模型的模块使用 ‘business’ 类别
依赖	itop-profiles-itil/1.0.0	依赖 iTop ITIL 配置文件模块

声明新配置文件

编辑 datamodel.sample-add-profile.xml，在 <user_rights> 内添加：

<profiles>
 <profile id="50" _delta="define">
 <name>Read-Only Except Requests</name>
 <description>Users with this profile are allowed to browse through all objects in the application and to create/modify user requests (either through the portal or in the normal application)</description>
 <groups>
 <group id="Portal">
 <actions>
 <action id="write">allow</action>
 <action id="delete">allow</action>
 </actions>
 </group>
 <group id="UserRequest">
 <actions>
 <action id="action:write">allow</action>
 <action id="stimulus:ev_close" xsi:type="stimulus">allow</action>
 <action id="stimulus:ev_reopen" xsi:type="stimulus">allow</action>
 </actions>
 </group>
 <group id="*">
 <actions>
 <action id="action:read">allow</action>
 <action id="action:bulk read">allow</action>
 </actions>
 </group>
 </groups>
 </profile>
 <profile id="51" _delta="define">
 <name>Read-Only No Portal Access</name>
 <description>Users with this profile are allowed to browse through all objects in the application but not to modify anything (even through the portal)</description>
 <groups>
 <group id="*">
 <actions>
 <action id="action:read">allow</action>
 <action id="action:bulk read">allow</action>
 </actions>
 </group>
 </groups>
 </profile>
</profiles>

说明

第一个配置文件（id=50）是 “Portal User” 配置文件的克隆，但允许在标准界面中导航
第二个配置文件（id=51）是纯只读配置
组 * 表示"任何类"
使用的组定义在 itop-profiles-itil 模块中

激活配置文件

修改完成后，需要重新运行安装以激活新配置文件。

部署

将模块文件夹复制到目标 iTop 的 extensions 目录并运行安装。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:add-profile-sample

版本：3_2_0/customization/add-profile-sample.txt · Last modified: 2026/03/16 14:03 by 127.0.0.1

Docs: 从 Ticket 中移除字段

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何从 iTop 类中完全移除字段。更多详细内容请参考 iTop 官方文档。

概述

移除字段需要识别该字段在 iTop XML 数据模型中的所有使用位置。以 UserRequest 的 urgency 字段为例，需要检查：

字段定义（fields/field@urgency）
类属性（naming、order、reconciliation 等）
生命周期（lifecycle）
展示（presentation）
方法（methods）
门户表单（module_designs/module_design@itop-portal/forms）
字典条目
OQL 查询（filter、Dashlets、Audit rules、Notifications 等）

移除标准数据模型中的字段可能破坏依赖该字段的 iTop 扩展的兼容性。

仅隐藏字段

在某些情况下，仅隐藏字段给用户可能已足够。

在门户中隐藏

创建表单时隐藏：

<form id="ticket-create" _delta="must_exist">
 <twig _delta="redefine">
 <div class="row">
 <div class="col-sm-6">
 <div class="form_field" data-field-id="impact"></div>
 </div>
 <div class="col-sm-6">
 <!-- 从默认门户中移除 urgency -->
 <!-- <div class="form_field" data-field-id="urgency"></div> -->
 </div>
 </div>
 </twig>
</form>

在控制台中隐藏

<presentation>
 <details _delta="must_exist">
 <items>
 <item id="col:col2">
 <items>
 <item id="fieldset:Ticket:Type">
 <items>
 <item id="urgency" _delta="delete"/>
 </items>
 </item>
 </items>
 </item>
 </items>
 </details>
</presentation>

仅隐藏不会完全移除字段，仍可通过 CSV 导出、列表配置、CSV 导入、REST/JSON API 访问。

完全移除字段

字段定义

<field id="urgency" _delta="delete">
</field>

类属性

检查 urgency 是否用于：

friendlyname
协调字段（CSV 导入）
过时逻辑
唯一性规则

生命周期标志

<state id="resolved">
 <flags>
 <attribute id="urgency" _delta="delete"/>
 </flags>
</state>

方法

检查 PHP 方法中是否有 $this->Get('urgency') 引用。例如 ComputePriority 方法需要修改。

展示

从 search、list 和 default_search 中移除：

<presentation>
 <search>
 <items>
 <item id="urgency" _delta="delete"/>
 </items>
 </search>
</presentation>

字典条目

理论上应删除对应字典条目，但不删除不影响 iTop 行为。

OQL 查询

检查以下位置是否使用了该字段：

数据模型中的 filter 标签
Dashlets
查询短语
审计规则
书签 URL
通知
配置文件参数

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:remove-field

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/remove-field.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 定义密码策略

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何创建自定义密码策略验证器。更多详细内容请参考 iTop 官方文档。

概述

iTop 不内置复杂的密码策略，但可以通过扩展实现自定义验证器。

可能的策略

黑名单策略

检查用户密码是否不在弱密码列表中。实现简单，本教程以此为例。

密码不能与前密码相同

更复杂，因为：

iTop 只存储密码哈希
盐值是随机的且难以提取

实现概要：

验证器需实现 iApplicationObjectExtension::OnDBUpdate() 和 UserLocalPasswordValidator 接口
将之前的密码哈希存储到专用类中
使用明文密码与哈希列表对比（不能比较两个哈希）
建议限制存储的哈希数量

实现验证器

创建实现 UserLocalPasswordValidator 接口的类：

class MyCustomPasswordValidator implements UserLocalPasswordValidator
{
 // 您的代码...
}

验证时返回 ValidatePassword 实例：

密码有效：new UserLocalPasswordValidity(true)
密码无效：new UserLocalPasswordValidity(false, $sMessage)

$sMessage 必须是已翻译的消息，按约定使用格式： 'Error:UserLocalPasswordValidator:<YourClassName>/ValidationFailed'

示例：黑名单验证器

class UserPasswordPolicyBlacklist implements UserLocalPasswordValidator
{
 public function __construct()
 {
 }

 public function ValidatePassword($proposedValue, UserLocal $oUserLocal, $config)
 {
 $sBlacklistFile = APPROOT.'data/passwordBlacklist.txt';

 $handle = @fopen($sBlacklistFile, "r");
 if (! $handle) {
 return new UserLocalPasswordValidity(
 false,
 'Unknown error : Failed to read the password blacklist.'
 );
 }
 try {
 while (($sBlackListPwd = fgets($handle, 4096)) !== false) {
 if (trim($sBlackListPwd) == trim($proposedValue))
 {
 $sMessage = Dict::S(
 'Error:UserLocalPasswordValidator:UserPasswordPolicyBlacklist/ValidationFailed'
 );
 return new UserLocalPasswordValidity(
 false,
 $sMessage
 );
 }
 }
 }
 finally
 {
 fclose($handle);
 }
 return new UserLocalPasswordValidity(true);
 }
}

data/passwordBlacklist.txt 每行一个禁用密码。可使用 SecLists 中的前 10000 个常用密码。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:password-policy

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/password-policy.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 定义依赖关系

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在 iTop 类之间定义新的依赖关系，用于影响分析。更多详细内容请参考 iTop 官方文档。

概述

假设创建了 FunctionalCI 下的新类 “Truc”，该类影响 ApplicationSolution 或 BusinessProcess。且影响规则因每个 ApplicationSolution 和 BusinessProcess 而异。

实现

<class id="Truc" _delta="define">
 <parent>FunctionalCI</parent>
 <properties>...</properties>
 <fields>
 <field id="functionalci_id" xsi:type="AttributeExternalKey">
 <sql>functionalci_id</sql>
 <filter><![CDATA[
 SELECT FunctionalCI WHERE finalclass IN ('ApplicationSolution', 'BusinessProcess')
 ]]></filter>
 <target_class>FunctionalCI</target_class>
 <is_null_allowed>true</is_null_allowed>
 <on_target_delete>DEL_MANUAL</on_target_delete>
 <tracking_level>all</tracking_level>
 <allow_target_creation>true</allow_target_creation>
 </field>
 </fields>
 <relations>
 <relation id="impacts">
 <neighbours>
 <neighbour id="business">
 <attribute>functionalci_id</attribute>
 </neighbour>
 </neighbours>
 </relation>
 </relations>
</class>

<class id="FunctionalCI" _delta="merge">
 <fields>
 <field id="trucs_list" xsi:type="AttributeLinkedSet" _delta="define">
 <linked_class>Truc</linked_class>
 <ext_key_to_me>functionalci_id</ext_key_to_me>
 <count_min>0</count_min>
 <count_max>0</count_max>
 <edit_mode>add_remove</edit_mode>
 <duplicates/>
 </field>
 <field id="redundancy" xsi:type="AttributeRedundancySettings" _delta="define">
 <sql>redundancy</sql>
 <relation_code>impacts</relation_code>
 <from_class>Truc</from_class>
 <neighbour_id>business</neighbour_id>
 <enabled>true</enabled>
 <enabled_mode>user</enabled_mode>
 <min_up>1</min_up>
 <min_up_mode>user</min_up_mode>
 <min_up_type>count</min_up_type>
 </field>
 </fields>
</class>

<class id="BusinessProcess" _delta="merge">
 <presentation>
 <details>
 <items>
 <item id="trucs_list" _delta="define">
 <rank>110</rank>
 </item>
 </items>
 </details>
 </presentation>
</class>

<class id="ApplicationSolution" _delta="merge">
 <presentation>
 <details>
 <items>
 <item id="trucs_list" _delta="define">
 <rank>110</rank>
 </item>
 </items>
 </details>
 </presentation>
</class>

关键点

relation id="impacts" 必须命名为 “impacts” 才能在影响分析中使用
neighbour 的 attribute 可以是指向外部键、LinkedSet 或一对查询（向下和向上）
AttributeRedundancySettings 允许配置冗余规则
min_up 定义最少需要多少个 “Truc” 处于运行状态

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:neighbours

版本：3_2_0/customization/neighbours.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 合并状态

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何使用 AttributeMetaEnum 创建基于子类字段值的合并状态。更多详细内容请参考 iTop 官方文档。

概述

Ticket 类使用特殊的 AttributeMetaEnum 类型属性来创建聚合状态，基于子工单类字段值自动计算。

您可以为 FunctionalCI 类创建类似的 AttributeMetaEnum 字段，基于一个或多个子类上定义的字段值计算。

添加计算状态

<class id="FunctionalCI" _created_in="itop-config-mgmt" _delta="must_exist">
 <fields>
 <field id="operational_status" xsi:type="AttributeMetaEnum" _delta="define">
 <values>
 <value id="production"><code>production</code></value>
 <value id="implementation"><code>implementation</code></value>
 <value id="obsolete"><code>obsolete</code></value>
 </values>
 <sql>operational_status</sql>
 <default_value>production</default_value>
 <mappings>
 <mapping id="FunctionalCI">
 <attcode>status</attcode>
 <metavalues>
 <metavalue id="implementation">
 <values>
 <value id="implementation"/>
 </values>
 </metavalue>
 <metavalue id="obsolete">
 <values>
 <value id="obsolete"/>
 <value id="inactive"/>
 </values>
 </metavalue>
 </metavalues>
 </mapping>
 </mappings>
 </field>
 </fields>
</class>

default_value：若没有任何映射适用，则使用此默认值
mapping 的 ID 必须是当前类或子类
attcode：至少一个子类上定义的属性代码
可定义多个映射，第一个匹配的映射决定 AttributeMetaEnum 的值

修改计算状态

示例：添加新的 escalated 值，并修改 UserRequest 的 rejected 映射逻辑：

<field id="operational_status" xsi:type="AttributeMetaEnum">
 <values _delta="must_exist">
 <value id="escalated" _delta="define">
 <code>escalated</code>
 </value>
 </values>
 <mappings>
 <mapping id="Ticket" _delta="must_exist">
 <metavalues>
 <metavalue id="escalated" _delta="define">
 <values>
 <value id="escalated_tto"/>
 <value id="escalated_ttr"/>
 </values>
 </metavalue>
 <metavalue id="closed" _delta="must_exist">
 <values>
 <value id="rejected" _delta="delete"/>
 </values>
 </metavalue>
 </metavalues>
 </mapping>
 <mapping id="Change" _delta="define">
 <attcode>status</attcode>
 <metavalues>
 <metavalue id="closed">
 <values>
 <value id="closed"/>
 <value id="rejected"/>
 </values>
 </metavalue>
 </metavalues>
 </mapping>
 </mappings>
</field>

此示例中：

UserRequest 的 rejected 状态映射为 ongoing（Ticket 的默认映射）
Change 的 rejected 状态仍映射为 closed

默认 3.1 定义

<field id="operational_status" xsi:type="AttributeMetaEnum">
 <values>
 <value id="ongoing">
 <code>ongoing</code>
 </value>
 <value id="resolved">
 <code>resolved</code>
 <style>
 <main_color>$ibo-lifecycle-success-state-primary-color</main_color>
 <complementary_color>$ibo-lifecycle-success-state-secondary-color</complementary_color>
 <decoration_classes>fas fa-check</decoration_classes>
 </style>
 </value>
 <value id="closed">
 <code>closed</code>
 <style>
 <main_color>$ibo-lifecycle-frozen-state-primary-color</main_color>
 <complementary_color>$ibo-lifecycle-frozen-state-secondary-color</complementary_color>
 <decoration_classes/>
 </style>
 </value>
 </values>
 <default_style>
 <main_color>$ibo-lifecycle-neutral-state-primary-color</main_color>
 <complementary_color>$ibo-lifecycle-neutral-state-secondary-color</complementary_color>
 <decoration_classes/>
 </default_style>
 <sql>operational_status</sql>
 <default_value>ongoing</default_value>
 <mappings>
 <mapping id="Ticket">
 <attcode>status</attcode>
 <metavalues>
 <metavalue id="resolved">
 <values>
 <value id="resolved"/>
 </values>
 </metavalue>
 <metavalue id="closed">
 <values>
 <value id="closed"/>
 <value id="rejected"/>
 </values>
 </metavalue>
 </metavalues>
 </mapping>
 </mappings>
</field>

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:meta-enum

Last modified: 2026/01/14 17:10 by127.0.0.1

版本：3_2_0/customization/meta-enum.txt · Last modified: 2026/01/14 17:10 by 127.0.0.1

Docs: 强制字段始终必填

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何强制字段在所有情况下必填。更多详细内容请参考 iTop 官方文档。

概述

本用例强制要求在所有 PhysicalDevice 及其子类（Server、Mobile Phone、Rack、Tablet、PDU 等）上填写 “location” 字段。

使用 ITSM Designer（Combodo 客户）

打开 PhysicalDevice 类
编辑 location_id 字段
在弹窗中勾选 Mandatory 复选框

使用 iTop 扩展

由于 location_id 字段直接在 PhysicalDevice 类上声明，只需将 is_null_allowed 设为 false：

<class id="PhysicalDevice">
 <fields>
 <field id="location_id">
 <is_null_allowed _delta="redefine">false</is_null_allowed>
 </field>
 </fields>
</class>

迁移注意事项

在 Setup（或工具包）时，若已有 PhysicalDevice 未记录位置，将收到错误消息。可以在 iTop 的 DB tools 菜单中重新运行此检查。修复对象不会阻止其打开和修改，但 DataSynchro 或 REST/JSON 脚本在修改其他字段时会失败。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:mandatory-field-always

版本：3_2_0/customization/mandatory-field-always.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 实现密码过期

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何实现密码过期功能。从 iTop 3.1.0 开始，此功能已内置在 Password Expiration Management 模块中。更多详细内容请参考 iTop 官方文档。

概述

注意：从 iTop 3.1.0 开始，此功能已内置在 Password Expiration Management 模块中，无需再手动实现。

本教程描述如何强制现有用户更改密码以符合新添加的复杂性策略。管理员将所有用户的 expiration 标志设为 expired，用户登录时将被要求更改密码。

插入检查点

class MyClass extends AbstractLoginFSMExtension
{
 public function ListSupportedLoginModes() { return array('form'); }

 protected function OnUsersOK(&$iErrorCode)
 {
 /* 在此处添加特定代码 */
 return LoginWebPage::LOGIN_FSM_CONTINUE;
 }
}

检查密码是否过期

$oUser = UserRights::GetUserObject();
if ($oUser->Get('expiration') == 'expired')
{
 /* 添加更多代码 */
}

请求新密码

public function DisplayChangePwdForm($bFailedLogin = false, $sIssue = null)
{
 $oTwigContext = new LoginTwigRenderer();
 $aVars = $oTwigContext->GetDefaultVars();
 $aVars['bFailedLogin'] = $bFailedLogin;
 $aVars['sIssue'] = $sIssue;
 $oTwigContext->Render($this, 'changepwdform.html.twig', $aVars);
}

模板 iTop/templates/login/password/changepwdform.html.twig 可复用，需移除 old_pwd 部分。同时有 changepwdform.js.twig 控制两次输入是否相等以及密码是否符合策略。

保存新密码

$sNewPwd = utils::ReadPostedParam('new_pwd', '', 'raw_data');
$oUser->Set('password', $sNewPwd);
$oUser->Set('expiration', 'limited');
$oUser->DB_Update();

错误处理

try
{
 if (!UserRights::ChangePassword($sOldPwd, $sNewPwd))
 {
 $oPage = self::NewLoginWebPage();
 $oPage->DisplayChangePwdForm(true);
 $oPage->output();
 exit;
 }
}
catch (CoreCannotSaveObjectException $e)
{
 $oPage = self::NewLoginWebPage();
 $oPage->DisplayChangePwdForm(true, $e->getIssue());
 $oPage->output();
 exit;
}

注意事项

当扩展自动化过期行为时，应修改 UserLocal:password:expiration 的翻译，以反映此行为。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:password-expiration

版本：3_2_0/customization/password-expiration.txt · Last modified: 2025/07/03 12:43 by 127.0.0.1

Docs: 属性的使用与限制

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍 iTop 中各种属性类型的使用限制和替代方案。更多详细内容请参考 iTop 官方文档。

概述

iTop 提供了多种属性类型，但并非每种属性都能在任何地方使用。本文档说明各种限制和替代方案。

字段在子类上的覆盖

字段在单个类上定义，具有属性：默认值、允许值、是否必填、依赖关系等。

在每个子类上，可以：

定义字段的显示位置
覆盖标签和工具提示
若字段定义中不是必填，则可通过 PHP 代码仅对该子类设为必填

必填字段的限制

某些属性类型不能设为必填：

AttributeLinkedSet：可通过 PHP 代码强制必填
AttributeCaselog：仅对第一个条目有效，之后不再为空

更改属性类型

在已有对象的情况下更改属性类型并非安全操作，取决于 MySQL/MariaDB 的能力：

操作	结果
增大 Text 字段大小	支持，但 Setup 期间可能耗时
减小 Text 字段大小	可能导致数据截断损坏
Date 改为 DateTime	时间部分设为 00:00:00
Text 改为 HTML	建议添加 `<format>html</format>` 标签而非更改类型
Duration/Integer/Decimal/Date/Datetime 改为 String	可能可行
String 改为 Duration/Integer/Decimal/Date/Datetime	假设数据格式正确才可能可行
LinkedSetIndirect 改为 LinkedSet	对数据库无影响，可安全回退

门户限制

以下属性类型在门户中不可编辑：

EnumSet 和 TagSet
File 和 Image
Duration

关系中的属性限制

链接类不支持以下字段类型：

Caselog
LinkedSet、LinkedSetIndirect
Text、HTML、Template
File、Image
Duration
TagSet、EnumSet

属性类型选择

多值选择

TagSet、EnumSet、LinkedSetIndirect：允许为单个对象字段设置多个值

单值选择

Enum 或 ExternalKey（指向 Typology 子类）：允许选择单个值

数据模型值 vs 数据库值

Enum 和 EnumSet：

缺点：添加新值需要 Designer MTP 或新扩展版本加 Setup
优点：OQL 过滤器可基于这些值，不依赖实例数据

Typology、TagSet 和 LinkedSetIndirect：

优点：添加值快速简单
缺点：基于这些值的 PHP 业务规则与数据耦合，文档化不足

更改枚举值

若在数据模型中更改 Enum 属性的允许值，而 iTop 中已有对象使用旧值：

数据模型视角的允许值限制为新值集合
每次 Setup 时，数据库视角的允许值 = 数据模型值 + 数据库中现有值
编辑时，可选值 = 当前值 + 所有数据模型定义值
搜索时，可选值仅限于数据模型定义值

过滤关系

外部键

AttributeExternalKey 的 filter XML 标签允许使用 OQL 查询过滤允许值。支持 $this->attcode 语法，其中 attcode 是当前类的有效字段 ID。

多对多关系

例如限制团队成员属于同一组织：

类	Person	lnkPersonToTeam	Team
字段	teams_list	person_id / team_id	persons_list
属性类型	LinkedSetIndirect	ExternalKey	LinkedSetIndirect
过滤方法	Search Form Prefill	XML filter	XML filter

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:attribute-limitation

版本：3_2_0/customization/attribute-limitation.txt · Last modified: 2026/06/10 17:31 by 127.0.0.1

Docs: 添加 1:1 关系

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在两个类之间创建一对一关系。更多详细内容请参考 iTop 官方文档。

概述

iTop 没有专门的 1:1 关系字段类型，但可以通过以下方式实现：

此方案仅为可选方案之一
关系只能在一边编辑
关系必须从两边可见

两个类之间的 1:1 关系

以 Person 和 CompanyCar 为例：一个人只能有一辆公司车，一辆车只能分配给一个人。

声明两个外部键

<field id="companycar_id" xsi:type="AttributeExternalKey" _delta="define">
 <filter><![CDATA[SELECT CompanyCar AS cc WHERE cc.person_id = 0]]></filter>
 <dependencies/>
 <sql>companycar_id</sql>
 <target_class>CompanyCar</target_class>
 <is_null_allowed>true</is_null_allowed>
 <on_target_delete>DEL_MANUAL</on_target_delete>
 <allow_target_creation>true</allow_target_creation>
</field>

<field id="person_id" xsi:type="AttributeExternalKey" _delta="define">
 <filter/>
 <dependencies/>
 <sql>person_id</sql>
 <target_class>Person</target_class>
 <is_null_allowed>true</is_null_allowed>
 <on_target_delete>DEL_MANUAL</on_target_delete>
 <allow_target_creation>false</allow_target_creation>
</field>

强制键同步

使用事件监听器在写入后同步两个外部键：

<event_listeners>
 <event_listener id="AfterWriteOneToOneRelationKeys" _delta="define">
 <event>EVENT_DB_AFTER_WRITE</event>
 <filters>
 <filter>Person</filter>
 <filter>CompanyCar</filter>
 </filters>
 <rank>0</rank>
 <code><![CDATA[function(Combodo\iTop\Service\Events\EventData $oEventData)
{
 $sCurrentClass = 'Person';
 $sKeyToCurrent = 'person_id';
 $sRemoteClass = 'CompanyCar';
 $sKeyToRemote = 'companycar_id';
 $oObject = $oEventData->Get('object');

 if (get_class($oObject) == $sCurrentClass) {
 $aChanges = $oObject->ListPreviousValuesForUpdatedAttributes();
 if (($oEventData->Get('is_new') || array_key_exists($sKeyToRemote, $aChanges))
 && ($oObject->Get($sKeyToRemote) > 0)) {
 $oNewRemote = MetaModel::GetObject($sRemoteClass, $oObject->Get($sKeyToRemote), false, true);
 if ($oNewRemote) {
 $oNewRemote->Set($sKeyToCurrent, $oObject->GetKey());
 $oNewRemote->DBUpdate();
 }
 }
 if (!$oEventData->Get('is_new') && array_key_exists($sKeyToRemote, $aChanges)
 && ($aChanges[$sKeyToRemote] > 0)) {
 $oOldRemote = MetaModel::GetObject($sRemoteClass, $aChanges[$sKeyToRemote], false, true);
 if ($oOldRemote) {
 $oOldRemote->Set($sKeyToCurrent, 0);
 $oOldRemote->DBUpdate();
 }
 }
 }
}]]></code>
 </event_listener>
 <event_listener id="OnDeleteOneToOneRelationKeys" _delta="define">
 <event>EVENT_DB_BEFORE_DELETE</event>
 <filters>
 <filter>Person</filter>
 <filter>CompanyCar</filter>
 </filters>
 <rank>0</rank>
 <code><![CDATA[function(Combodo\iTop\Service\Events\EventData $oEventData)
{
 $sCurrentClass = 'Person';
 $sKeyToCurrent = 'person_id';
 $sRemoteClass = 'CompanyCar';
 $sKeyToRemote = 'companycar_id';
 $oObject = $oEventData->Get('object');

 if ((get_class($oObject) == $sCurrentClass) && ($oObject->Get($sKeyToRemote) > 0)) {
 $oOldRemote = MetaModel::GetObject($sRemoteClass, $oObject->Get($sKeyToRemote), false, true);
 if ($oOldRemote) {
 $oOldRemote->Set($sKeyToCurrent, 0);
 $oOldRemote->DBUpdate();
 }
 }
}]]></code>
 </event_listener>
</event_listeners>

防止在一边编辑

为避免无限更新循环，锁定一边的编辑：

public function evtSetInitialAttributeFlags(Combodo\iTop\Service\Events\EventData $oEventData)
{
 $this->ForceInitialAttributeFlags('person_id', OPT_ATT_HIDDEN);
}
public function evtSetAttributeFlags(Combodo\iTop\Service\Events\EventData $oEventData)
{
 $this->ForceAttributeFlags('person_id', OPT_ATT_READONLY);
}

允许"抢占"

若要将已分配的车辆重新分配给另一个驾驶员：

修改过滤器允许抢占
在更新前一个驾驶员时，需要避免无限循环

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:one-to-one-relation

版本：3_2_0/customization/one-to-one-relation.txt · Last modified: 2025/05/19 16:10 by 127.0.0.1

Docs: 添加 n:n 关系

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在两个类之间创建多对多（n:n）关系。更多详细内容请参考 iTop 官方文档。

概述

本教程演示如何在两个类之间创建多对多关系。以 Person 和 Location 之间的关系为例，记录人员的认证级别和最后访问时间。

iTop 中的多对多关系存储为带有特殊 XML 标签 <is_link>（值为 1）的类，告诉 iTop 如何在界面、控制台和门户中处理此类。

限制

创建链接类时，以下字段类型不受支持：

Caselog
LinkedSet、LinkedSetIndirect
Text、HTML、Template
File、Image
Duration
TagSet、EnumSet

在以下场景中会出现问题：

门户中：编辑包含这些属性的链接将始终失败
控制台中编辑宿主对象时：编辑包含这些属性的链接将始终失败
控制台中读取宿主对象时：弹出窗口中编辑链接支持大多数属性，但 File 和 Image 除外

门户 ManageBrick

若在 ManageBrick 中显示 LinkedSetAttribute，将产生错误：

DataTables warning: table id=table-UserRequest - Ajax error.

链接类定义

属性

class id：命名约定以 lnk 开头，后跟按字母顺序的第一个类名，然后 To，最后第二个类名
parent：cmdbAbstractObject
category：bizmodel
db_table：iTop 约定使用小写的类名
naming 和 reconciliation：通常使用两个相关对象来命名和标识关系

<class id="lnkLocationToPerson" _delta="define">
 <parent>cmdbAbstractObject</parent>
 <properties>
 <category>bizmodel</category>
 <abstract>false</abstract>
 <db_table>lnklocationtoperson</db_table>
 <is_link>1</is_link>
 <naming>
 <attributes>
 <attribute id="location_id"/>
 <attribute id="person_id"/>
 </attributes>
 </naming>
 <reconciliation>
 <attributes>
 <attribute id="location_id"/>
 <attribute id="person_id"/>
 </attributes>
 </reconciliation>
 </properties>
</class>

字段

链接类需要两个 AttributeExternalKey：person_id 和 location_id。

<class id="lnkLocationToPerson" _delta="must_exist">
 <fields _delta="define">
 <field id="location_id" xsi:type="AttributeExternalKey">
 <sql>location_id</sql>
 <filter/>
 <dependencies/>
 <is_null_allowed>false</is_null_allowed>
 <target_class>Location</target_class>
 <on_target_delete>DEL_AUTO</on_target_delete>
 </field>
 <field id="person_id" xsi:type="AttributeExternalKey">
 <sql>person_id</sql>
 <filter/>
 <dependencies/>
 <is_null_allowed>false</is_null_allowed>
 <target_class>Person</target_class>
 <on_target_delete>DEL_AUTO</on_target_delete>
 </field>
 <field id="accreditation" xsi:type="AttributeEnum">
 <sql>accreditation</sql>
 <default_value>restricted</default_value>
 <is_null_allowed>false</is_null_allowed>
 <values>
 <value id="restricted"><code>restricted</code></value>
 <value id="unrestricted"><code>unrestricted</code></value>
 </values>
 <display_style>radio_horizontal</display_style>
 </field>
 <field id="last_visit" xsi:type="AttributeDate">
 <sql>last_visit</sql>
 <is_null_allowed>true</is_null_allowed>
 </field>
 </fields>
</class>

展示

details 和 list 为必填，default_search 和 search 为可选。

<class id="lnkLocationToPerson">
 <presentation _delta="define">
 <list>
 <items>
 <item id="location_id"><rank>10</rank></item>
 <item id="person_id"><rank>20</rank></item>
 <item id="accreditation"><rank>30</rank></item>
 <item id="last_visit"><rank>40</rank></item>
 </items>
 </list>
 <details>
 <items>
 <item id="col:col1">
 <items>
 <item id="location_id"><rank>10</rank></item>
 <item id="person_id"><rank>20</rank></item>
 <item id="accreditation"><rank>30</rank></item>
 <item id="last_visit"><rank>40</rank></item>
 </items>
 <rank>10</rank>
 </item>
 </items>
 </details>
 </presentation>
</class>

<dictionaries>
 <dictionary id="EN US" _delta="must_exist">
 <entries>
 <entry id="Class:lnkLocationToPerson/Name" _delta="define"><![CDATA[%2$s is a visitor of %1$s]]></entry>
 <entry id="Class:lnkLocationToPerson/Attribute:person_id" _delta="define"><![CDATA[Visitor]]></entry>
 <entry id="Class:lnkLocationToPerson/Attribute:location_id" _delta="define"><![CDATA[Location]]></entry>
 <entry id="Class:lnkLocationToPerson/Attribute:accreditation" _delta="define"><![CDATA[Accreditation]]></entry>
 <entry id="Class:lnkLocationToPerson/Attribute:last_visit" _delta="define"><![CDATA[Last visit]]></entry>
 </entries>
 </dictionary>
</dictionaries>

唯一性规则

若要求在特定 Person 和 Location 之间只能有一个链接：

<class id="lnkLocationToPerson" _delta="must_exist">
 <properties>
 <uniqueness_rules>
 <rule id="no_duplicate" _delta="define">
 <attributes>
 <attribute id="person_id"/>
 <attribute id="location_id"/>
 </attributes>
 <filter/>
 <disabled>false</disabled>
 <is_blocking>true</is_blocking>
 </rule>
 </uniqueness_rules>
 </properties>
</class>

远程类引用

Person 类

在 Person 详情中显示授权位置：

<fields>
 <field id="locations_list" xsi:type="AttributeLinkedSetIndirect" _delta="define">
 <ext_key_to_remote>location_id</ext_key_to_remote>
 <ext_key_to_me>person_id</ext_key_to_me>
 <linked_class>lnkLocationToPerson</linked_class>
 <count_min>0</count_min>
 <count_max>0</count_max>
 <duplicates>false</duplicates>
 </field>
</fields>
<presentation>
 <details>
 <items>
 <item id="locations_list" _delta="define">
 <rank>200</rank>
 </item>
 </items>
 </details>
</presentation>

Location 类

类似地在 Location 中显示授权访客：

<field id="persons_list" xsi:type="AttributeLinkedSetIndirect" _delta="define">
 <ext_key_to_remote>person_id</ext_key_to_remote>
 <ext_key_to_me>location_id</ext_key_to_me>
 <linked_class>lnkLocationToPerson</linked_class>
 <count_min>0</count_min>
 <count_max>0</count_max>
 <duplicates>false</duplicates>
</field>

3.1 特殊显示

iTop 3.1.0+ 可以使用类似 TagSet 和 EnumSet 的 widget 显示多对多关系。将 display_style 设置为 property（默认值为 tab）：

<field id="locations_list" _delta="must_exist">
 <display_style _delta="force">property</display_style>
</field>

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:add-relation

2026/06/10 17:31 by127.0.0.1

版本：3_2_0/customization/add-relation.txt · Last modified: 2026/06/10 17:31 by 127.0.0.1

Docs: 添加保密属性

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在 iTop 中为特定对象添加保密属性，限制特定用户角色的读写访问。更多详细内容请参考 iTop 官方文档。

目标

需求： 特定对象上的某些信息需要对部分用户限制可见性。

约束： 目前 iTop 按类和组织全局控制读取访问，没有字段级别的选项。

方案： 本教程提供一种实现保密属性的方式：

读取权限限制为具有特定角色的用户，其他用户只能看到 *
写入权限按角色分配
保密属性可以是任意类型：成本、HTML 描述、图片、案例日志等

设计概述

为确保该字段不被未授权用户读取，我们将其放入一个独立的类中。

注意： 基于当前用户隐藏对象详情中的字段是一种虚假的安全性。通过配置对象列表中显示的字段，任何人都可以获取该字段的值。

实现步骤：

创建保密类
更新宿主类
建立一对一关系的连接

保密类

这个新类只包含：

一个硬编码的友好名称 ******
一个 value 字段，类型对应需要存储的保密值
一个指向宿主类的外部键（宿主类本应包含该保密属性）

该类必须设置 category = grant_by_profile, application：

grant_by_profile 允许控制谁可以看到它。需要创建一个包含此新类的组，以及包含该组的配置文件
application 将其从 “所有类” 组提供的读取访问中移除

定义一个摘要卡片，显示 “value” 和宿主对象的友好名称。

可以放在任何模块中，但放在宿主类所在的模块更合理。

防止从保密属性类编辑外部键 → 设为只读（2 个事件）
当不存在外部键时，通过 CheckToWrite 阻止创建此类对象（事件）
从表单中隐藏该字段，但将 host_id_friendlyname 放入表单以帮助记住正在修改的内容

宿主类

创建一个指向新创建类的外部键：

添加过滤器，只列出未分配的保密属性（实际上避免提供任何已有项）
确保 AfterWrite → 更新保密属性的外部键
当外部键 != 0 时阻止编辑，但仍可以更改其内容

在保密类上创建一个 LinkedSet 属性，使用外部键 host_id，并将其显示为 “properties”。

同步键

参考添加 1:1 关系。

局限性

无法阻止保密属性的纯创建，可能导致孤儿值
无法在弹出窗口中编辑属性

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:confidential-attribute

版本：3_2_0/customization/confidential-attribute.txt · Last modified: 2025/05/20 12:39 by 127.0.0.1

Docs: 添加状态和转换

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何为 UserRequest 添加新状态和转换，以标识等待第三方提供商的状态。更多详细内容请参考 iTop 官方文档。

概述

本教程将：

为 UserRequest 添加新状态，表示等待第三方提供商
添加新事件，将用户请求移入该新状态
添加两个转换，允许工单移入和移出此状态
为需要执行此转换的用户启用访问权限

使用 ITSM Designer（Combodo 客户）

创建新状态

点击工具栏的 Add State 按钮
填写必填属性并点击 Create State

添加事件

点击 Events 标题旁的小按钮
事件代码按约定命名为 ev_xxxx，如 ev_pending_provider
类型选择 End User action（用户界面中可提议的转换）
事件的标签将应用于所有使用该事件的转换

添加转换

点击工具栏按钮或右键状态选择 New Transition
选择起始状态、事件和目标状态
点击 OK 创建新转换

启用访问权限

为 Support Agent 配置文件启用此权限：

导航到 User Rights 主标签页
点击 Profiles 子标签页
选择 Support Agent 配置文件
在 UserRequest 前点击编辑图标
找到 ev_pending_provider 事件，将权限从 Undefined 改为 Allow

使用 iTop 扩展

声明新状态

<!-- 向现有 status 添加新状态值 -->
<field id="status" _delta="must_exist">
 <values>
 <value id="pending_provider" _delta="define">
 <code>pending_provider</code>
 </value>
 </values>
</field>

添加字典条目：

<entry id="Class:UserRequest/Attribute:status/Value:pending_provider" _delta="define">
 <![CDATA[Pending provider]]>
</entry>

添加事件（刺激）

<stimuli>
 <stimulus id="ev_pending_provider" xsi:type="StimulusUserAction" _delta="define"/>
</stimuli>

<entry id="Class:UserRequest/Stimulus:ev_pending_provider" _delta="define">
 <![CDATA[Wait for Provider]]>
</entry>

添加转换

<states>
 <state id="assigned" _delta="must_exist">
 <transitions>
 <transition id="ev_pending_provider" _delta="define">
 <stimulus>ev_pending_provider</stimulus>
 <target>pending_provider</target>
 <actions/>
 </transition>
 </transitions>
 </state>
 <state id="pending_provider" _delta="define">
 <flags/>
 <transitions>
 <transition id="ev_assign">
 <stimulus>ev_assign</stimulus>
 <target>assigned</target>
 <actions/>
 </transition>
 </transitions>
 <inherit_flags_from>assigned</inherit_flags_from>
 </state>
</states>

启用访问权限

<profile id="5" _delta="must_exist">
 <groups>
 <group id="UserRequest" _delta="must_exist">
 <actions>
 <action id="ev_pending_provider" _delta="define">allow</action>
 </actions>
 </group>
 </groups>
</profile>

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:add-state-transition

版本：3_2_0/customization/add-state-transition.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 统计在某状态中花费的时间

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何使用秒表属性统计工单在特定状态中花费的时间。更多详细内容请参考 iTop 官方文档。

概述

本教程统计每张工单等待第三方提供商的时间。需要：

在 UserRequest 类上添加秒表属性，在 pending_provider 状态时计时
添加子项字段显示等待提供商的时间
仅在 UserRequest 的某些状态中显示总等待时间

假设已添加 “pending_provider” 状态和 2 个转换。

使用 ITSM Designer（Combodo 客户）

添加秒表

点击 Stopwatches 标题旁的小按钮
填写代码、标签，选择状态 pending_provider

追踪时间

创建新字段，类型选择 Stopwatch Value
选择秒表，值选择 Total time spent

显示秒表

将字段添加到展示/详情视图中。在 Schema 标签页中，在秒表不相关的状态中隐藏此字段。

使用 iTop 扩展

添加秒表

<field id="providerstopwatch" xsi:type="AttributeStopWatch" _delta="define">
 <states>
 <state id="pending_provider">pending_provider</state>
 </states>
 <working_time/>
 <thresholds/>
 <always_load_in_tables>true</always_load_in_tables>
</field>

<entry id="Class:UserRequest/Attribute:providerstopwatch" _delta="define">
 <![CDATA[Provider stopwatch]]>
</entry>

追踪时间

此步骤必须执行，才能在表单中显示或通过 OQL 查询：

<field id="pending_provider_delay" xsi:type="AttributeSubItem" _delta="define">
 <target_attcode>providerstopwatch</target_attcode>
 <item_code>timespent</item_code>
</field>

可用子项代码：timespent、started、laststart、stopped

<entry id="Class:UserRequest/Attribute:pending_provider_delay" _delta="define">
 <![CDATA[Provider time spent]]>
</entry>

显示秒表

<presentation>
 <details _delta="must_exist">
 <items>
 <item id="col:col1">
 <items>
 <item id="fieldset:Ticket:moreinfo">
 <items>
 <item id="pending_provider_delay" _delta="define">
 <rank>80</rank>
 </item>
 <item id="providerstopwatch" _delta="define">
 <rank>90</rank>
 </item>
 </items>
 </item>
 </items>
 </item>
 </items>
 </details>
</presentation>

按状态控制显示

在 new 状态中隐藏 pending_provider_delay（会传播到所有链式状态）
在 resolved 状态中设为只读

<lifecycle>
 <states>
 <state id="new" _delta="must_exist">
 <flags>
 <attribute id="pending_provider_delay" _delta="define">
 <hidden/>
 </attribute>
 </flags>
 </state>
 <state id="resolved" _delta="must_exist">
 <flags>
 <attribute id="pending_provider_delay" _delta="define">
 <read_only/>
 </attribute>
 </flags>
 </state>
 </states>
</lifecycle>

秒表行为

从未启动：所有子项为空
首次进入 pending_provider：秒表运行中，Elapsed 不可用，Started 和 LastStart 相等
首次返回 assigned：秒表停止，Elapsed 可用，Stopped 有记录
再次进入 pending_provider：秒表重新运行，Started 不变，LastStart 更新
再次返回 assigned：秒表停止，Elapsed 累计，注意不等于 Started 和 Stopped 的差值

秒表自动计算，用户不可编辑。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:add-state

Last modified: 2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/add-state.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 委派管理员工具菜单

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何将 “管理员工具” 菜单委派给非管理员用户。更多详细内容请参考 iTop 官方文档。

概述

从 iTop 2.5 开始，可以将管理员工具菜单授予非管理员用户。

限制

以下菜单不能委派给非管理员：

Schedule Backup
Log Management（除非使用 Log Management 2.0.1+）
iTop Hub

某些类（如历史相关类）没有组织，因此向具有 “Allowed Organizations” 的用户提供 “Run Query” 访问权限会产生安全漏洞。

菜单可见性

从 XML 1.5 版本开始，可以基于类和操作权限控制任何菜单的访问。只有具有该类操作权限的人才能看到该菜单。

默认由类操作控制的管理菜单：

菜单	控制类	操作
Users	User	write
Profile	Profile	write
Notifications	Trigger	write
Audit	AuditCategory	write
Run Query	ResourceRunQueriesMenu	write
Query phrasebook	Query	write
Export	ResourceAdminMenu	write
Data Model	ResourceRunQueriesMenu	write
Universal Search	ResourceAdminMenu	write
Synchronization Data Sources	SynchroDataSource	write

预定义组：

组 ID	默认包含菜单	包含类
User	用户账户、配置文件	User、URP_UserOrg、URP_UserProfile、URP_Profiles
Audit	审计、运行查询	AuditCategory、AuditRule、ResourceRunQueriesMenu
Notification	通知、运行查询	Trigger、Action、lnkTriggerAction、ResourceRunQueriesMenu
Query	查询短语手册、运行查询	Query、QueryOQL、ResourceRunQueriesMenu
SynchroData	同步数据源	SynchroDataSource
LogManagement	日志中心	ResourceLogMenu
AdminTools	所有上述菜单	所有上述类

分步示例

将 “Export Menu” 委派给 “Config Manager” 配置文件：

创建抽象类

<class id="RessourceExportMenu" _delta="define">
 <parent>AbstractResource</parent>
 <properties>
 <comment>/* Export Menu access control. */</comment>
 <abstract>true</abstract>
 <category>grant_by_profile</category>
 </properties>
 <presentation/>
 <methods/>
</class>

覆盖菜单定义

<menu id="ExportMenu" xsi:type="WebPageMenuNode" _delta="must_exist">
 <enable_class _delta="redefine">RessourceExportMenu</enable_class>
 <enable_action _delta="redefine">UR_ACTION_MODIFY</enable_action>
</menu>

完成组和配置文件定义

<user_rights>
 <groups>
 <group id="Export" _delta="define">
 <classes>
 <class id="RessourceExportMenu"/>
 </classes>
 </group>
 </groups>
 <profiles>
 <profile id="3" _delta="must_exist">
 <groups>
 <group id="Export" _delta="define">
 <actions>
 <action id="action:write">allow</action>
 </actions>
 </group>
 </groups>
 </profile>
 </profiles>
</user_rights>

可创建的配置文件

以下是一些可创建的配置文件示例：

User Manager（id=43）— 管理用户账户
Notification Manager（id=44）— 管理触发器和动作
Audit Manager（id=45）— 管理审计规则
Query Manager（id=46）— 管理查询短语手册
SynchroData Manager（id=47）— 管理同步数据源
Admin Tools Manager（id=48）— 管理所有管理工具

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:delegate_rights

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/delegate_rights.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 为 Server 类添加字段

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何为现有 iTop 类添加新字段。这是学习创建 iTop 扩展的第一个入门教程。更多详细内容请参考 iTop 官方文档。

概述

本教程将逐步介绍如何为现有 iTop 对象添加新字段。以在 Server 对象上添加一个文本字段为例。

使用 ITSM Designer（Combodo 客户）

Combodo 的 iTop Professional 或 Essential 客户无需创建扩展，可直接使用 ITSM Designer：

从 iTop 导航到 ITSM Designer
打开 Classes 标签页，选择 Server 类
点击顶部工具栏的创建新字段图标
选择属性类型，填写字段属性（包括标签）
切换到 Presentation 标签页的 Details view，拖拽新字段到所需位置
点击 Move To Production 按钮推送更改

使用 iTop 扩展

准备工作

在开发机器上安装 iTop
支持 UTF-8 的文本编辑器（Windows 可用 Wordpad、PSPad 或 Notepad++）

定制流程

安装 iTop 开发实例
安装工具包辅助定制
使用扩展创建向导创建空模块
将模块复制到 extensions 文件夹并运行安装
修改模块并使用工具包验证

创建模块

使用扩展创建向导，填写以下信息：

标签	值	说明
模块名称	sample-add-attribute	以 `itop-` 和 `combodo-` 开头的名称保留给 Combodo 使用
模块标签	Add Attribute Sample	安装向导中显示的标签
模块版本	1.0.0	使用 X.Y.Z 三位版本号
类别	business	修改数据模型的模块应使用 ‘business’ 类别
依赖	itop-config-mgmt/2.0.0	依赖 iTop 配置管理模块

安装空模块

将 zip 文件解压到 extensions 文件夹，运行 http://your_itop/setup/ 重新安装，选择 Update an existing instance。

添加字段

编辑 datamodel.sample-add-attribute.xml，在 <classes> 标签内添加：

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

使用工具包验证后，点击 Update iTop Code 应用更改。此时数据库已添加新列，但界面尚未显示。

使字段可见

将新字段添加到 Server 的详情展示中。编辑 XML 文件，在 <presentation> 中重新定义 details：

<presentation>
 <details _delta="redefine">
 <items>
 <!-- ... 现有字段 ... -->
 <item id="col:col2">
 <items>
 <item id="fieldset:Server:otherinfo">
 <items>
 <item id="description">
 <rank>30</rank>
 </item>
 <item id="notes">
 <rank>40</rank>
 </item>
 </items>
 </item>
 </items>
 </item>
 </items>
 </details>
</presentation>

添加字段标签

编辑 en.dict.sample-add-attribute.php，添加字典条目：

Dict::Add('EN US', 'English', 'English', array(
 'Class:Server/Attribute:notes' => 'Additional Notes',
));

高级方案

为避免与其他扩展冲突，可以不重新定义整个 details，而是精确定位插入点：

<presentation>
 <details>
 <items>
 <item id="col:col2" _delta="must_exist">
 <items>
 <item id="fieldset:Server:otherinfo" _delta="must_exist">
 <items>
 <item id="notes" _delta="define">
 <rank>40</rank>
 </item>
 </items>
 </item>
 </items>
 </item>
 </items>
 </details>
</presentation>

部署

将模块文件夹复制到目标 iTop 的 extensions 目录并运行安装。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:add-attribute-sample

版本：3_2_0/customization/add-attribute-sample.txt · Last modified: 2026/03/16 14:06 by 127.0.0.1

Docs: 为类添加生命周期

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何为 PhysicalDevice 类添加简单的生命周期。更多详细内容请参考 iTop 官方文档。

概述

本教程演示如何为 PhysicalDevice 添加生命周期，使用现有的状态值并定义状态间的转换。

需要：

确定承载生命周期状态的枚举属性（若不存在则创建）
定义默认状态（对象创建时自动使用）
定义不同的状态和刺激事件
为每个状态定义：前一个状态（作为字段标志的基础）、可用的转换、字段的必填/只读/隐藏标志

使用 ITSM Designer（Combodo 客户）

选择类，进入 Lifecycle 标签页，点击 Add State 图标
选择用于存储生命周期状态的枚举字段
点击 Initialize，枚举字段的现有值将被创建为状态
若枚举有默认值，则作为初始状态；否则第一个值被使用（可随时修改）

使用 iTop 扩展

数据模型

PhysicalDevice 已有 status 枚举字段可用于承载生命周期。假设管理 4 个状态：implementation、production、obsolete、stock。标准数据模型中 CI 创建时状态为 production，这里改为 implementation：

<class id="PhysicalDevice">
 <fields>
 <field id="status">
 <default_value _delta="redefine">implementation</default_value>
 </field>
 </fields>
</class>

生命周期定义

添加生命周期标签、状态字段和状态列表：

<class id="PhysicalDevice" _delta="must_exist">
 <lifecycle _delta="define">
 <attribute>status</attribute>
 <stimuli>
 <stimulus id="ev_move2prod" xsi:type="StimulusUserAction"/>
 <stimulus id="ev_obsolete" xsi:type="StimulusUserAction"/>
 <stimulus id="ev_stock" xsi:type="StimulusUserAction"/>
 </stimuli>
 <states>
 <state id="implementation">
 <flags/>
 <transitions>
 <transition id="ev_move2prod">
 <stimulus>ev_move2prod</stimulus>
 <target>production</target>
 <flags/>
 <actions/>
 </transition>
 </transitions>
 </state>
 <state id="production">
 <flags/>
 <transitions>
 <transition id="ev_obsolete">
 <target>obsolete</target>
 <actions/>
 </transition>
 <transition id="ev_stock">
 <target>stock</target>
 <actions/>
 </transition>
 </transitions>
 </state>
 <state id="obsolete">
 <flags/>
 <transitions/>
 </state>
 <state id="stock">
 <flags/>
 <transitions>
 <transition id="ev_move2prod">
 <stimulus>ev_move2prod</stimulus>
 <target>production</target>
 <flags/>
 <actions/>
 </transition>
 </transitions>
 </state>
 </states>
 </lifecycle>
</class>

状态转换图：

implementation --ev_move2prod--> production --ev_stock--> stock
|
+--ev_obsolete--> obsolete

有关生命周期的更多可能性，请参阅 XML 数据模型参考。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:add-lifecycle

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/add-lifecycle.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 新的认证方式

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍 iTop 2.7+ 的认证流程以及如何通过扩展添加新的认证方式。更多详细内容请参考 iTop 官方文档。

概述

从 iTop 2.7.0 开始，添加新的认证方式变得更加容易。本文档介绍：

iTop 2.7 的登录流程
扩展登录流程的新接口（API）
如何扩展认证流程

认证行为

iTop 2.7 的认证流程使用 FSM（有限状态机）。

通用算法

自动机从 start 状态开始
对每个状态调用所有相关插件
当所有插件都接受继续时，自动机进入下一个状态

登录状态

状态	说明
start	入口状态，首次调用或错误/注销后
login mode detection	检测使用哪个登录插件
read credentials	读取凭据，显示表单或重定向到外部认证系统
check credentials	验证凭据是否有效
credentials ok	验证凭据对应有效的 iTop 用户
user ok	额外用户检查，如双因素认证
connected	用户已连接
error	发生错误，下一个状态为 start

主要变量

$_SESSION['login_state'] — 当前状态
$_SESSION['login_mode'] — 登录模式
$_SESSION['can_logoff'] — 是否允许注销

认证接口

iLoginFSMExtension

低级插件接口，包含两个方法：

ListSupportedLoginModes() — 返回支持的登录模式数组
LoginAction($sLoginState, &$iErrorCode) — 每个状态调用

返回值：

LOGIN_FSM_RETURN_ERROR — 发生错误
LOGIN_FSM_RETURN_OK — 登录成功，流程终止
LOGIN_FSM_RETURN_IGNORE — 继续到下一个插件或状态

AbstractLoginFSMExtension

抽象类，实现 iLoginFSMExtension 并为每个状态提供回调函数：

OnStart(&$iErrorCode)
OnModeDetection(&$iErrorCode)
OnReadCredentials(&$iErrorCode)
OnCheckCredentials(&$iErrorCode)
OnCredentialsOK(&$iErrorCode)
OnUsersOK(&$iErrorCode)
OnConnected(&$iErrorCode)
OnError(&$iErrorCode)

iLogoutExtension

用户注销时调用。

ListSupportedLoginModes() — 返回支持的登录模式
LogoutAction() — 用户注销时调用

扩展认证流程

要添加新的认证方式：

提供扩展 AbstractLoginFSMExtension（推荐）或实现 iLoginFSMExtension 的 PHP 类
可选：提供实现 iLogoutExtension 的 PHP 类
在 allowed_login_types 配置中注册新模式

登录 API

// 验证凭据对应有效用户
public static function LoginWebPage::CheckUser($sAuthUser, $sAuthPassword='', $sAuthentication='external')

// 登录成功时存储用户信息到会话
public static function LoginWebPage::OnLoginSuccess($sAuthUser, $sAuthentication, $sLoginMode)

// 检查已登录用户是否仍然有效
public static function LoginWebPage::CheckLoggedUser(&$iErrorCode)

用户预配

在 AbstractLoginFSMExtension::OnCheckCredentials() 中创建用户和人员：

private function DoUserProvisioning($sLogin, $sEmail, $sFirstName, $sLastName, $sOrganization, $aProfiles)
{
 if (!Config::Get('synchronize_user')) {
 return;
 }
 try {
 if (LoginWebPage::FindUser($sLogin, false)) {
 return; // 用户已存在
 }
 $oPerson = LoginWebPage::FindPerson($sEmail);
 if ($oPerson == null) {
 if (!Config::Get('synchronize_contact')) {
 return;
 }
 $oPerson = LoginWebPage::ProvisionPerson($sFirstName, $sLastName, $sEmail, $sOrganization);
 }
 LoginWebPage::ProvisionUser($sLogin, $oPerson, $aProfiles);
 } catch (Exception $e) {
 IssueLog::Error($e->getMessage());
 }
}

示例：CAS 认证

authent-cas 模块实现 CAS 认证，包含 CASLoginExtension 类：

ListSupportedLoginModes() — 返回 ['cas']
OnReadCredentials() — 重定向到 CAS 服务器认证
OnCheckCredentials() — 检查凭据并预配用户
OnCredentialsOK() — 验证 iTop 用户有效性
OnConnected() — 检查用户仍然有效
LogoutAction() — 同时从 CAS 服务器注销

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:authentication

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/authentication.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 用户保护

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何防止因修改人员组织而导致用户意外被禁用。更多详细内容请参考 iTop 官方文档。

概述

若用户定义了 “Allowed organizations” 并关联到 Person，则该 Person 的组织必须在允许的列表中。此检查在 iTop 3.0.0 中已添加到用户对象创建/修改和 Person 删除时，但修改 Person 组织到不在允许列表中的组织的情况仍未被保护。

本教程添加对 Person 类的保护。

DoCheckToWrite

必须覆盖此函数：

public function DoCheckToWrite()
{
 if (array_key_exists('org_id', $this->ListChanges()) && ($this->HasUserAccount(true))) {
 $iNewOrg = $this->Get('org_id');
 $aUserOrgs = [$iNewOrg];
 $sHierarchicalKeyCode = MetaModel::IsHierarchicalClass('Organization');
 if ($sHierarchicalKeyCode !== false) {
 $sOrgQuery = 'SELECT Org FROM Organization AS Org JOIN Organization AS Root ON Org.'
 .$sHierarchicalKeyCode.' ABOVE Root.id WHERE Root.id = :id';
 $oOrgFilter = new DBObjectSearch::FromOQL_AllData($sOrgQuery);
 $oOrgFilter->AllowAllData(true);
 $oOrgSet = new DBObjectSet($oOrgFilter, [], ['id' => $iNewOrg]);
 while ($aRow = $oOrgSet->FetchAssoc()) {
 $oOrg = $aRow['Org'];
 $aUserOrgs[] = $oOrg->GetKey();
 }
 }
 $oUserSet = $this->GetUsers(true);
 while($oUser = $oUserSet->Fetch())
 {
 if (!UserRights::IsAdministrator($oUser)) {
 $oSet = $oUser->get('allowed_org_list');
 if ($oSet->Count() > 0) {
 $bFound = false;
 while ($oOrg = $oSet->Fetch()) {
 if (in_array($oOrg->Get('allowed_org_id'), $aUserOrgs)) {
 $bFound = true;
 break;
 }
 }
 if (!$bFound) {
 $this->m_aCheckErrors[] = $oUser->Get('login').": "
 .Dict::S('Class:User/Error:AllowedOrgsMustContainUserOrg');
 }
 }
 }
 }
 }
 return parent::DoCheckToWrite();
}

辅助函数

可选的 Helper 函数：

public function GetUsers($bActiveOnly = false)
{
 $sOQL = $bActiveOnly ? 'SELECT User WHERE contactid = :person'
 : "SELECT User WHERE contactid = :person AND status='active'";
 $oFilter = DBSearch::FromOQL($sOQL, array('person' => $this->GetKey()));
 $oFilter->AllowAllData(true);
 $oUserSet = new DBObjectSet($oFilter);
 return $oUserSet;
}

public function HasUserAccount($bActiveOnly = false)
{
 static $bHasUserAccount = null;
 if (is_null($bHasUserAccount)) {
 $bHasUserAccount = ($this->GetUsers($bActiveOnly)->Count() > 0);
 }
 return $bHasUserAccount;
}

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:user-protection

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/user-protection.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 在 PHP 中添加 TagSet

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在 PHP 方法中向 TagSet 属性添加特定值。更多详细内容请参考 iTop 官方文档。

概述

在 PHP 方法中向 TagSet 属性添加特定值。

前提条件

熟悉教程中使用的语法
已创建扩展
熟悉仪表盘设计和 OQL

示例场景

假设有一个 Bug 类：

字符串字段 version（继承自 Sprint 的外部字段）
TagSet versions（记录修复该 Bug 的产品版本）
默认情况下，在 Bug 解决时确保至少包含 Sprint 的 “version”

代码示例

public function PrefillTransitionForm(&$aContextParam)
{
 switch ($aContextParam['stimulus']) {
 case 'ev_resolve':
 try {
 // 获取版本字符串
 $sVersion = $this->Get('version');
 // 获取 Bug 应修复的版本（ormTagSet 对象）
 $oVersions = $this->Get('versions');
 // 获取对应标签的 TagSetFieldData 代码
 $Tag = $oVersions->GetTagFromLabel($sVersion);
 // 若不存在则添加
 $oVersions->Add($Tag);
 // 设置回对象
 $this->Set('versions', $oVersions);
 } catch (Exception $e) {
 // 若标签不是有效值，GetTagFromLabel() 会抛出异常
 IssueLog::Warning($e);
 }
 break;
 }
}

注意事项

若标签不是 TagSet 中的有效值，将抛出异常：

CoreUnexpectedValue: 4.0.0 is not defined as a valid tag for Bug:versions in...

Docs: 在 PHP 中添加日志条目

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在 PHP 方法中向 Caselog 属性添加日志条目。更多详细内容请参考 iTop 官方文档。

概述

在 PHP 方法中向 Caselog 属性添加特定日志条目。

前提条件

熟悉教程中使用的语法
已创建扩展
熟悉仪表盘设计和 OQL

实现方法

Get() 在 AttributeCaselog 上返回一个 ormCaselog 对象
使用 ormCaselog 的公共方法 AddLogEntry()
将修改后的日志设置回当前对象
使用 $this->DBUpdate() 确保持久化

代码示例

public function PrefillTransitionForm(&$aContextParam)
{
 switch ($aContextParam['stimulus']) {
 case 'ev_resolve':
 // 获取日志，返回的是 ormCaselog 对象
 $oLog = $this->Get('public_log');
 // 添加日志条目：文本、创建者标签、可选的用户 ID
 $oLog->AddLogEntry(
 'The text to add to the log<br>With html tag if needed',
 'A text description of the User who added this entry',
 :current_user_id
 );
 // 将修改后的日志设置回当前对象
 $this->Set('public_log', $oLog);
 break;
 }
}

Docs: 在 Team 上添加仪表盘

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在 Team 对象上添加仪表盘属性，以显示团队相关的信息。更多详细内容请参考 iTop 官方文档。

概述

在每个 Team 对象上显示一个仪表盘标签页，包含团队相关的信息，例如：

分配给该团队的开放工单列表
仅限活跃成员的列表
至少有一名团队成员所在的位置列表

参考 OQL 查询

开放工单

SELECT UserRequest WHERE STATUS IN ('assigned') AND team_id=:this->id
UNION SELECT Incident WHERE STATUS IN ('assigned') AND team_id=:this->id
UNION SELECT Problem WHERE STATUS IN ('assigned') AND team_id=:this->id

活跃成员

SELECT Person AS p
 JOIN lnkPersonToTeam AS l ON l.person_id = p.id
 WHERE l.team_id = :this->id AND STATUS='active'

成员所在位置

SELECT Location AS L
 JOIN Person AS P ON P.location_id=L.id
 JOIN lnkPersonToTeam AS l1 ON l1.person_id=P.id
 JOIN Team AS T ON l1.team_id=T.id
 WHERE T.id=:this->id

使用 ITSM Designer（Combodo 客户）

进入 Team 类，Schema 标签页创建新字段
字段代码：overview
类型选择：Dashboard
设置标签

仪表盘属性可作为对象的额外标签页显示，查询可使用当前对象的上下文。

勾选 Is User Editable 允许普通用户创建自定义版本
管理员始终可以自定义仪表盘

使用 iTop 扩展

创建仪表盘属性

<class id="Team" _delta="must_exist">
 <fields>
 <field id="dashboard" xsi:type="AttributeDashboard" _delta="define">
 <is_user_editable>true</is_user_editable>
 <definition>
 <layout>DashboardLayoutOneCol</layout>
 <title/>
 <auto_reload>
 <enabled>false</enabled>
 <interval>300</interval>
 </auto_reload>
 <cells>
 <cell id="0">
 <rank>0</rank>
 <dashlets>
 <dashlet id="0" xsi:type="DashletEmptyCell">
 <rank>0</rank>
 </dashlet>
 </dashlets>
 </cell>
 </cells>
 </definition>
 </field>
 </fields>
 <presentation>
 <details>
 <items>
 <item id="dashboard" _delta="define">
 <rank>100</rank>
 </item>
 </items>
 </details>
 </presentation>
</class>

设计仪表盘

先部署一个空仪表盘版本，在 iTop 中直接设计：

使用 :this->id 引用当前团队 ID
设计完成后导出为 XML
替换初始 <definition> 的内容

示例导出：

<?xml version="1.0"?>
<dashboard xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <layout>DashboardLayoutOneCol</layout>
 <title/>
 <auto_reload>
 <enabled>false</enabled>
 <interval>300</interval>
 </auto_reload>
 <cells>
 <cell id="0">
 <rank>0</rank>
 <dashlets>
 <dashlet id="1" xsi:type="DashletObjectList">
 <rank>0</rank>
 <title>Members</title>
 <query>SELECT Person AS p
 JOIN lnkPersonToTeam AS lnk ON lnk.person_id = p.id
 WHERE lnk.team_id=:this->id
 </query>
 <menu>true</menu>
 </dashlet>
 </dashlets>
 </cell>
 </cells>
</dashboard>

添加字典条目

<dictionary id="EN US" _delta="must_exist">
 <entries>
 <entry id="Class:Team/Attribute:dashboard" _delta="define">
 <![CDATA[Overview]]>
 </entry>
 </entries>
</dictionary>

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:add-dashboard-attribute

版本：3_2_0/customization/add-dashboard-attribute.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 重新定义字典条目

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何修改 iTop 中显示的标签以及创建新的字典条目。更多详细内容请参考 iTop 官方文档。

概述

通过修改字典条目，可以自定义 iTop 中显示的各类标签。了解字典条目命名规范有助于正确定义条目。

使用 ITSM Designer（Combodo 客户）

字典编辑器

在 ITSM Designer 的 Editors 主标签页下，使用 Dictionary 子标签页全局编辑字典条目。

搜索

使用表单搜索要编辑的字典条目。可以按条目的代码（如 Class:Person）或内容搜索。若同时提供代码和内容条件，则只显示同时匹配两者的条目。

修改条目

修改后，点击每个条目旁的验证标记，或使用顶部的 Apply All 按钮应用所有更改。

缺失翻译

可以搜索尚未翻译的条目。

新建条目

若字典条目不存在（例如来自 XML 门户的新条目），可使用 New 按钮创建。

删除条目

搜索条目，选择要删除的条目，然后点击删除按钮。

使用 iTop 扩展

修改 XML 条目

首先找到条目的代码。通用标签位于 your-itop/dictionary/en.dictionary.itop.xxx.php 文件中：

ui — 用户界面标签
core — 字段类型和通用对象标签

数据模型类相关的标签位于 your-itop/datamodels/2.x/xxx/en.dict.xxx.php 中。

找到代码后，在扩展中重新定义其值。使用 _delta="redefine" 替换现有值，使用 _delta="force" 在不确定是否存在时强制设置。

示例：将 UserRequest 的 “Requestor” 改为 “Beneficiary”：

<dictionary id="EN US" _delta="must_exist">
 <entries>
 <entry id="Class:UserRequest/Attribute:caller_id" _delta="redefine">
 <![CDATA[Beneficiary]]>
 </entry>
 <entry id="Class:UserRequest/Attribute:caller_id+" _delta="force">
 <![CDATA[Choose the client person who will get the requested service]]>
 </entry>
 </entries>
</dictionary>

新建 XML 条目

使用 _delta="define" 创建新条目，若条目已存在则会失败。

<dictionary id="EN US" _delta="must_exist">
 <entries>
 <entry id="Class:Team/Attribute:dashboard" _delta="define">
 <![CDATA[Overview]]>
 </entry>
 </entries>
</dictionary>

如需为多语言定义标签，可复制上述 XML 结构并修改语言代码。

使用字典文件

除在 XML 中定义外，也可在 PHP 文件中按语言定义字典条目。详见iTop 翻译。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:add-dictionay-entry

版本：3_2_0/customization/add-dictionay-entry.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 转换方法

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍在 iTop 生命周期转换中可用的预定义 PHP 方法及其参数。更多详细内容请参考 iTop 官方文档。

概述

在 XML 生命周期定制中，当对象发生特定转换时，可能需要执行某些动作。这些动作是对象类的 PHP 方法。您既可以编写自定义方法，也可以使用 DBObject 上已声明的现有方法。

前提条件

熟悉教程中使用的语法
已创建扩展

参数说明

$sAttCode

字符串类型，必须是当前类的有效属性代码
不提供有效性检查，若代码无效将导致致命错误
可在 XML 类定义的 field id 中找到
也可在 iTop 的数据模型查看器中找到，使用属性的代码而非标签

$value

固定字面量值，通常为字符串，也可以是数字

可用方法

AddValue($sAttCode, $iValue = 1)

递增或递减当前对象的字段值。

不对字段类型或值进行控制，无效组合将导致 iTop 崩溃
$value 应为数字或浮点数，可为负数
$sAttCode 应为 Decimal、Integer、Percentage 或 Duration 类型的属性代码

<actions>
 <action id="1">
 <verb>AddValue</verb>
 <params>
 <param id="1" xsi:type="string">assign_counter</param>
 <param id="2" xsi:type="integer">1</param>
 </params>
 </action>
</actions>

Copy($sDestAttCode, $sSourceAttCode)

将当前对象的一个字段内容复制到另一个字段。

不检查属性代码的有效性和一致性
如需要会将 HTML 转换为文本
日期和数字自动转换为文本

Reset($sAttCode)

将指定字段重置为默认值。

ResetStopWatch($sAttCode)

重置秒表属性。

会验证是否为当前对象的秒表属性
清空 TimeSpent
重置后如同从未停止过
若正在运行，则从头开始计时

Set($sAttCode, $value)

为指定属性设置固定值。不检查代码格式或值的有效性。

例如设置 Ticket 的 caller_id 时，$value 必须是 iTop 中存在的 Person 对象的数字 ID
枚举类型的 $value 应使用代码而非标签

Set('caller_id', 6);

SetIfNull($sAttCode, $value)

与 Set 相同，但如果字段已有值则保持不变。

SetComputedDate($sAttCode, $sModifier = ‘’, $sAttCodeSource = ‘’)

从源日期（省略则使用当前时间）计算新日期，应用修饰符后复制到目标字段。

修饰符示例：

+5 days — 5 天后
-3 weeks — 3 周前
first weekday of next month — 下月第一个工作日
monday of next week — 下周一

SetComputedDateIfNull($sAttCode, $sModifier = ‘’, $sAttCodeSource = ‘’)

与 SetComputedDate 相同，但如果字段已有值则保持不变。

SetCurrentPerson($sAttCode)

将当前执行方法的用户的关联 Person 设置到指定字段。

若字段是指向 Person 类或其父类的外部键：复制关联 Person 的 ID
若字段是指向其他类的外部键：将导致崩溃
若字段是字符串：放入关联 Person 的友好名称

SetCurrentDate($sAttCode)

将 Date 或 DateTime 属性设置为当前时间。

SetCurrentDateIfNull($sAttCode)

与 SetCurrentDate 相同，但如果字段已有值则保持不变。

SetElapsedTime($sAttCode, $sRefAttCode, $sWorkingTimeComputer = null)

检查 itop/core/dbobject.class.inc.php 中的代码了解详情。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:actions-on-transitions

版本：3_2_0/customization/actions-on-transitions.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 转换时执行动作

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在工单状态转换时执行动作，以统计工单重新打开次数为例。更多详细内容请参考 iTop 官方文档。

概述

本用例演示如何统计用户请求被重新打开的次数。需要：

为用户请求添加计数器字段
可选：禁用历史追踪
修改生命周期，在从 resolved 到 assigned 的转换时调用方法
修改展示以显示计数器
为计数器字段添加标签

使用 ITSM Designer（Combodo 客户）

添加字段

进入 UserRequest 类，在 Schema 标签页创建新字段
字段代码：reopen_counter（仅小写字母，无空格或特殊字符）
类型选择：Number (Integer)
定义标签
可选：禁用历史追踪

修改生命周期

进入 Lifecycle 标签页
在图中选择从 resolved 到 assigned 的转换
在右侧面板点击动作列表底部的按钮
在对话框中选择方法 AddValue
目标字段选择 reopen_counter
值输入 1

修改展示

进入 Presentation 标签页，将 reopen_counter 添加到 UserRequest 的详情视图中。

使用 iTop 扩展

添加计数器字段

<classes>
 <class id="UserRequest" _delta="must_exist">
 <fields>
 <field id="reopen_count" xsi:type="AttributeInteger" _delta="define">
 <sql>reopen_count</sql>
 <default_value>0</default_value>
 <is_null_allowed>true</is_null_allowed>
 </field>
 </fields>
 </class>
</classes>

禁用历史追踪（可选）

若不需要记录计数器每次变更的历史：

<field id="reopen_count">
 <tracking_level>none</tracking_level>
</field>

在转换时调用方法

在从 resolved 到 assigned 的转换时递增计数器：

<state id="resolved">
 <transitions>
 <transition id="ev_reopen">
 <actions _delta="redefine">
 <action>
 <verb>AddValue</verb>
 <params>
 <param xsi:type="attcode">reopen_count</param>
 <param xsi:type="int">1</param>
 </params>
 </action>
 </actions>
 </transition>
 </transitions>
</state>

声明自定义 PHP 方法

若预定义方法不满足需求，可创建自定义方法：

public function MyLifecycleMethod($sAttCode, $iIncrement = 1)
{
 if (MetaModel::IsValidAttCode(get_class($this), $sAttCode)
 && is_numeric($iIncrement)
 && (MetaModel::GetAttributeDef(get_class($this), $sAttCode) instanceof AttributeInteger))
 {
 $iNew = $this->Get($sAttCode) + $iIncrement;
 $this->Set($sAttCode, $iNew);
 }
 return true;
}

添加展示

将计数器添加到 UserRequest 详情页的 SLA 报告字段集中：

<class id="UserRequest" _delta="must_exist">
 <presentation>
 <details>
 <items>
 <item id="col:col3">
 <items>
 <item id="fieldset:Ticket:SLA">
 <items>
 <item id="reopen_count" _delta="define">
 <rank>80</rank>
 </item>
 </items>
 </item>
 </items>
 </item>
 </items>
 </details>
 </presentation>
</class>

添加标签

<entry id="Class:UserRequest/Attribute:reopen_count" _delta="define">重新打开计数器</entry>

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:add-counter

版本：3_2_0/customization/add-counter.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 转换时字段必填

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在生命周期转换时或特定状态中强制字段必填。更多详细内容请参考 iTop 官方文档。

概述

当对象具有生命周期时，iTop 数据模型允许在转换和状态级别指定哪些字段必须填写。

使用 ITSM Designer（Combodo 客户）

转换时必填

要求从 New 状态移动到 Assigned 状态时填写 Service 字段：

在 Lifecycle 标签页中选择转换
设置字段为必填

状态中必填

要求所有处于 Assigned 状态的 UserRequest 都定义 Service：

在 Lifecycle 标签页中选择状态
设置字段为必填

使用 iTop 扩展

转换时必填

<class id="UserRequest">
 <lifecycle>
 <states>
 <state id="new">
 <transitions>
 <transition id="ev_assign" _delta="must_exist">
 <flags>
 <attribute id="service_id" _delta="define">
 <mandatory/>
 </attribute>
 </flags>
 </transition>
 </transitions>
 </state>
 </states>
 </lifecycle>
</class>

状态中必填

<class id="UserRequest" _delta="must_exist">
 <lifecycle>
 <states>
 <state id="assigned" _delta="must_exist">
 <flags>
 <attribute id="service_id" _delta="define">
 <mandatory/>
 </attribute>
 </flags>
 </state>
 </states>
 </lifecycle>
</class>

迁移注意事项

Setup 时无可见效果，但不符合要求的对象将无法在控制台或门户中修改，直到提供 Service。建议创建审计规则检索不符合要求的对象并修复。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:mandatory-on-transition

版本：3_2_0/customization/mandatory-on-transition.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 状态延迟后通知

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在工单在特定状态中停留超过指定时间后发送通知。更多详细内容请参考 iTop 官方文档。

概述

当工单在 assigned 状态中超过 2 小时和 6 小时时分别通知相关人员。需要：

定义实现 iMetricComputer 的 PHP 类，计算固定延迟作为秒表目标
在 UserRequest 上添加秒表属性，在 assigned 状态时计时，使用固定目标
设置工作时间计算方式

使用 ITSM Designer（Combodo 客户）

定义目标

需要 “Designer PHP developer” 配置文件。定义 6 小时延迟，在 2 小时（33%）和 6 小时（100%）时通知：

class FixedDelayMetric implements iMetricComputer
{
 public static function GetDescription()
 {
 return "iTop configurable delay in hours, 6 by default";
 }
 public function ComputeMetric($oObject)
 {
 $iRes = 3600 * MetaModel::GetConfig()->GetModuleSetting('itop-tickets', 'pending_delay', '6');
 return $iRes;
 }
}

在 iTop 配置文件中添加：

$MyModuleSettings = array(
 'itop-tickets' => array(
 'pending_delay' => 36,
 ),
);

添加秒表

创建秒表，选择状态 assigned
在 33% 处添加阈值
在 100% 处添加阈值

定义工作时间

使用 DefaultWorkingTimeComputer 进行 24x7 计时
使用 SLAComputation 考虑工作时段（通常仅适用于子工单类）

使用 iTop 扩展

定义目标

class FixedDelayMetric implements iMetricComputer
{
 public static function GetDescription()
 {
 return "Fixed 6h delay";
 }
 public function ComputeMetric($oObject)
 {
 $iRes = 6 * 3600; // 目标以秒为单位
 return $iRes;
 }
}

添加秒表

<field id="fixdelay" xsi:type="AttributeStopWatch" _delta="define">
 <states>
 <state id="assigned">assigned</state>
 </states>
 <working_time>DefaultWorkingTimeComputer</working_time>
 <thresholds/>
 <goal>FixedDelayMetric</goal>
 <always_load_in_tables>true</always_load_in_tables>
</field>

<entry id="Class:UserRequest/Attribute:fixdelay" _delta="define">
 <![CDATA[6h Delay]]>
</entry>

配置通知

在 iTop 中定义基于阈值的触发器，并链接到通知动作。使用新创建的秒表 fixdelay，可用阈值为 33 和 100。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:add-stopwatch

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/add-stopwatch.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 追踪对象创建者

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何追踪对象的创建者。更多详细内容请参考 iTop 官方文档。

概述

对象历史记录中包含创建者信息，但难以通过 OQL 查询，也无法构建按创建者统计的仪表盘。解决方案：

在 Ticket 或 UserRequest 上添加 creator_id 字段（指向 Person 类的外部键）
自动存储对象创建者
通过查询历史记录更新现有工单

添加 creator_id 字段

参考为 Server 类添加字段。

若决定在 UserRequest、Incident、Change 等详情中显示 creator_id，建议将其设为只读。

自动填充创建者

Ticket 创建时自动使用当前用户的关联人员初始化 creator_id：

protected function OnInsert()
{
 $this->Set('creator_id', UserRights::GetContactId());
 parent::OnInsert();
}

然后运行 Setup 使新字段生效。

数据初始化

1. 运行查询

SELECT co, p FROM CMDBChangeOp AS co
 JOIN CMDBChange AS c ON co.change=c.id
 JOIN Ticket AS t ON co.objkey=t.id
 JOIN USER AS u ON c.user_id=u.id
 JOIN Person AS p ON u.contactid=p.id
WHERE co.finalclass="CMDBChangeOpCreate"

2. CSV 导入

使用高级模式导入两列：

co.object_id -> Ticket id（主键）
p.id（主键）-> Creator

导入到 UserRequest 和 Incident。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:tracking-creator

版本：3_2_0/customization/tracking-creator.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 额外的创建状态

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在 iTop 中允许对象在除默认状态外的其他生命周期状态中创建。更多详细内容请参考 iTop 官方文档。

目标

假设我们有一个带有生命周期的 Task 类，默认情况下 Task 在 new 状态中创建。我们希望也允许在另一个状态 template 中创建 Task。

使用 Designer

前提条件： 必须是 Combodo 客户。

此操作只能由 Combodo 执行。

使用 iTop 扩展

前提条件： 请先查看添加状态和转换教程。

在 template 状态声明中，只需添加 3 行即可：

<states>
 <state id="template">
 <initial_state_path>
 <state_ref _delta="define">new</state_ref>
 </initial_state_path>

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:create-in-different-states

版本：3_2_0/customization/create-in-different-states.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: LinkedSet 相关值

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在 iTop 3.1+ 中处理 LinkedSet 相关值的计算与约束。更多详细内容请参考 iTop 官方文档。

场景

假设我们有一个 Stock 对象类，以及一个通过 1:n 关系与之关联的 StockMove 类：

Stock 对象有可用商品数量
当有人要消耗库存中的某些商品时，创建一个带有所需数量的 StockMove 对象
如果所需数量超过库存中的可用商品，iTop 必须拒绝此消耗

在 iTop 3.1 之前： 可以在 Stock 类的 OnUpdate / OnInsert 中计算，但这假设没有其他方式可以在不编辑 Stock 对象的情况下创建/修改/删除 LinkedSet 中的对象。

自 iTop 3.1 起： 可以仅编辑关系，而宿主 Stock 对象处于只读模式，因此 OnUpdate / OnInsert 不会触发，计算值也不会更新。可以使用 AttributeLinkedSet(Indirect) XML 标签 <edit_when>in_host_edition</edit_when> 阻止在 Stock 对象只读时编辑 LinkedSet，但这不够用户友好。

下面介绍另一种替代方案。

计算 LinkedSet 依赖值

我们需要计算依赖于 stockmoves_list 这个 LinkedSet 属性的内容，并将其存储在 Stock 类上。

计算方法为 ComputeAndUpdateStock()，它计算并更新 Stock 字段 remaining_quantity
StockMove 对象有一个指向 MyClass 的必填外部键，以及 quantity 和 type（表示是消耗还是补充库存）
我们希望无论 LinkedSet 内容以何种方式修改，该值始终保持最新
StockMove 的创建、修改或删除都需要重新计算 Stock 的 remaining_quantity

实现步骤：

在 LinkedSet 属性上标记 <with_php_computation>true</with_php_computation>
监听 EVENT_DB_LINKS_CHANGED 事件并执行计算

<fields>
 <field id="stockmoves_list" xsi:type="AttributeLinkedSet">
 <ext_key_to_me>stock_id</ext_key_to_me>
 <linked_class>StockMove</linked_class>
 <tracking_level>none</tracking_level>
 <count_min/>
 <count_max/>
 <with_php_constraint>true</with_php_constraint>
 <with_php_computation>true</with_php_computation>
 <edit_mode>none</edit_mode>
 </field>
</fields>
<event_listeners>
 <event_listener id="OnLinksChanged" _delta="define">
 <event>EVENT_DB_LINKS_CHANGED</event>
 <callback>OnLinksChanged</callback>
 <rank>0</rank>
 </event_listener>
</event_listeners>
<methods>

public function OnLinksChanged(Combodo\iTop\Service\Events\EventData $oEventData)
{
 $this->ComputeAndUpdateStock();
 // $this->DBUpdate(); 在 $this 上不需要
 // 如果 ComputeAndUpdateStock() 修改了 $this，iTop 将自动执行 DBUpdate()
}

protected function OnUpdate()
{
 $aChanges = $this->ListChanges();

 /* 不要在此计算，因为 EVENT_DB_LINKS_CHANGED 会被调用一次并执行计算
 if (array_key_exists('stockmoves_list', $aChanges)) {
 $this->ComputeAndUpdateStock();
 } */
}

阻止 LinkedSet 的无效变更

目标： 阻止导致库存为负值的 StockMove 创建/修改/删除。

当条件只能由宿主对象检查时，阻止对 stockmoves_list 的操作：

方法 ComputeStock() 计算库存的理论 “剩余数量”，但不更新 remaining_quantity 字段，仅用于检查
同样，StockMove 对象有指向 MyClass 的必填外部键、数量 quantity 和类型 type
我们希望阻止导致库存出现负值的 StockMove 创建/修改/删除

实现步骤：

在 LinkedSet 上标记 <with_php_constraint>true</with_php_constraint>
监听 EVENT_DB_CHECK_TO_WRITE 事件，在 LinkedSet 上检查条件，如需阻止则添加 Check Issue

<fields>
 <field id="stockmoves_list" xsi:type="AttributeLinkedSet">
 <ext_key_to_me>stock_id</ext_key_to_me>
 <linked_class>StockMove</linked_class>
 <tracking_level>none</tracking_level>
 <count_min/>
 <count_max/>
 <with_php_constraint>true</with_php_constraint>
 <with_php_computation>true</with_php_computation>
 <edit_mode>none</edit_mode>
 </field>
</fields>
<event_listeners>
 <event_listener id="CheckStockAvailability" _delta="define">
 <event>EVENT_DB_CHECK_TO_WRITE</event>
 <callback>CheckStockAvailability</callback>
 <rank>0</rank>
 </event_listener>
</event_listeners>

public function CheckStockAvailability()
{
 // 如果所需数量在库存中不可用则停止
 // ComputeStock() 不修改 $this，仅计算
 if ($this->ComputeStock() < 0) {
 // 添加 CheckIssue 将阻止链接对象的创建/修改或删除
 $this->AddCheckIssue(Dict::Format('Stock:Error:NotEnoughQuantityInStock'));
 }
}

其他用例

在机柜（Enclosure）中可以定义其总容量（U 大小）
机柜包含的设备也有 U 大小
一个设备只能位于单个机柜中
机柜上的 devices_list 是 LinkedSet 属性
可以使用上述方法阻止已安装设备的 U 大小总和超过机柜的 U 大小

局限性

假设在一个团队中，我们希望确保团队成员中男性和女性的数量 “相同，正负不超过两人”。

每次添加或删除成员时，规则会自动检查，当变更会破坏规则时阻止添加或删除
但可以通过更改某个团队成员的性别来绕过规则，因为此更改不会触发团队检查

如果删除一个人员，删除传播是否正确执行？如果团队引发了 CheckToWrite 问题，这是否会被阻止？

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:event-db-links-changed

版本：3_2_0/customization/event-db-links-changed.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 隐藏转换

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何限制工单的转换操作，仅允许处理人、其经理或管理员执行。更多详细内容请参考 iTop 官方文档。

目标

在本教程中，我们将了解如何阻止除处理人、其经理或管理员之外的其他人转换工单。

我们将使用 EVENT_ENUM_TRANSITIONS 事件的回调。

实现逻辑

获取处理人（agent）的 Person 对象
检查是否处于应隐藏转换的情况：
- 当前连接用户的 ID（UserRights::GetContactId()）既不是 agent_id 也不是其 manager_id
- 当前用户不是 iTop 管理员（!UserRights::IsAdministrator()）
- 工单处于 “Assigned” 或 “Pending” 状态
然后使用 $this->DenyTransition($sStimulusCode) 移除应受限的激励（stimulus）
- 可以隐藏不存在的激励，不会产生任何影响

XML 配置

<classes>
 <class id="UserRequest">
 <event_listeners>
 <event_listener id="HideTransitionsIfNotAgent" _delta="define">
 <event>EVENT_ENUM_TRANSITIONS</event>
 <rank>10</rank>
 <callback>HideTransitionsIfNotAgent</callback>
 </event_listener>
 </event_listeners>
 <methods>
 <method id="HideTransitionsIfNotAgent" _delta="define">
 <comment>/**
 * 如果当前用户既不是处理人，也不是其经理
 * 且当前用户不是管理员
 * 且 UserRequest 处于某些状态
 * 则隐藏某些转换
 */</comment>
 <static>false</static>
 <access>public </access>
 <code><![CDATA[public function HideTransitionsIfNotAgent(Combodo\iTop\Service\Events\EventData $oEventData)....

PHP 代码

public function HideTransitionsIfNotAgent(Combodo\iTop\Service\Events\EventData $oEventData)
{
 $iAgent = $this->Get('agent_id');
 if ($iAgent > 0) {
 $oAgent = MetaModel::GetObject('Person', $iAgent, true, true);
 $iManager = $oAgent->get('manager_id');
 $iCurrentPerson = UserRights::GetContactId();

 if ((!in_array($iCurrentPerson, [$iAgent, $iManager]) && !UserRights::IsAdministrator())
 && (in_array($this->Get('status'), ['assigned', 'pending']))) {
 $this->DenyTransition('ev_pending');
 $this->DenyTransition('ev_resolve');
 }
 }
}

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:hide-transition

版本：3_2_0/customization/hide-transition.txt · Last modified: 2025/11/18 18:05 by 127.0.0.1

Docs: 添加附件时记录日志

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在添加或删除附件时自动向工单日志添加记录。更多详细内容请参考 iTop 官方文档。

目标

需求：每次有人向工单添加附件时，在 UserRequest 工单的日志中添加一条记录。

利用事件机制，可以订阅特定事件并在事件触发时执行方法。

在 UserRequest 类上创建一个方法来添加日志条目
订阅两个不同的事件并指定回调方法

添加日志条目

public function AddLogEntryOnAttachment(Combodo\iTop\Service\Events\EventData $oEventData)
{
 // 获取日志，返回的对象是 ormCaselog，即一个对象
 $oLog = $this->Get('public_log');
 // 从事件中获取 Attachment 对象
 $oAttachment = $oEventData->Get('attachment');
 // 从 Attachment 获取 ormDocument
 $oDocument = $oAttachment->Get('contents');

 // 测试哪个"事件"触发了回调
 if ($oEventData->GetEvent() == EVENT_ADD_ATTACHMENT_TO_OBJECT)
 // 添加一条日志条目，包含附件文件名
 $oLog->AddLogEntry('Add an attachment: '.$oDocument->GetFileName());
 else
 $oLog->AddLogEntry('Removed attachment: '.$oDocument->GetFileName());
 // 将修改后的日志设置回当前 UserRequest
 $this->Set('public_log', $oLog);
 $this->DBUpdate();
}

订阅事件

这里我们订阅了 2 个不同的事件，但使用相同的回调方法来处理：

<class id="UserRequest" _delta="must_exist">
 <event_listeners>
 <event_listener id="AddLogEntryOnAttachment" _delta="define">
 <event>EVENT_ADD_ATTACHMENT_TO_OBJECT</event>
 <callback>AddLogEntryOnAttachment</callback>
 <rank>0</rank>
 </event_listener>
 <event_listener id="AddLogEntryOnAttachmentRemoval" _delta="define">
 <event>EVENT_REMOVE_ATTACHMENT_FROM_OBJECT</event>
 <callback>AddLogEntryOnAttachment</callback>
 <rank>0</rank>
 </event_listener>
 </event_listeners>
</class>

完整增量

<?xml version="1.0" encoding="UTF-8"?>
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="3.1">
 <classes>
 <class id="UserRequest">
 <event_listeners>
 <event_listener id="AddLogEntryOnAttachment" _delta="define">
 <event>EVENT_ADD_ATTACHMENT_TO_OBJECT</event>
 <callback>AddLogEntryOnAttachment</callback>
 <rank>0</rank>
 </event_listener>
 <event_listener id="AddLogEntryOnAttachmentRemoval" _delta="define">
 <event>EVENT_REMOVE_ATTACHMENT_FROM_OBJECT</event>
 <callback>AddLogEntryOnAttachment</callback>
 <rank>0</rank>
 </event_listener>
 </event_listeners>
 <methods>
 <method id="AddLogEntryOnAttachment" _delta="define">
 <static>false</static>
 <access>public</access>
 <type>EventListener</type>
 <code><![CDATA[ public function AddLogEntryOnAttachment(Combodo\iTop\Service\Events\EventData $oEventData) { blablabla... } ]]>
 </code>
 </method>
 </methods>
 </class>
 </classes>
</itop_design>

iTop 3.1.0+ 但低于 3.1.2 的替代方案

在 iTop 3.1.0+ 但低于 3.1.2 的版本中，可以响应 Attachment 类的事件：

EVENT_DB_AFTER_WRITE
EVENT_DB_AFTER_DELETE

然后检索与附件关联的对象类、对象键，如果是 UserRequest 则添加日志条目。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:log-attachment

版本：3_2_0/customization/log-attachment.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 按条件强制字段必填

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在特定条件下强制字段必填。更多详细内容请参考 iTop 官方文档。

目标

此用例是强制提供字段的一种方式。

提交前检查

仅生产环境中的服务器

在此用例中，我们希望确保：

创建时，不提议位置
修改生产环境中的服务器时，位置变为必填

<class id="PhysicalDevice">
 <fields>
 <field id="location_id">
 <!-- 如果状态更改，强制重新计算 location_id 标志 -->
 <dependencies _delta="redefine">
 <attribute id="org_id"/>
 <attribute id="status"/>
 </dependencies>
 </field>
 </fields>
</class>
<class id="Server" _delta="must_exist">
 <event_listeners>
 <event_listener id="evtSetInitialFlags" _delta="define">
 <!-- 事件 ID 不需要与函数名相同，但也可以相同 -->
 <event>EVENT_DB_SET_INITIAL_ATTRIBUTES_FLAGS</event>
 <rank>10</rank>
 <!-- 回调必须是现有类方法的名称。名称自由 -->
 <callback>evtSetInitialFlags</callback>
 </event_listener>
 <event_listener id="evtSetAttributeFlags" _delta="define">
 <event>EVENT_DB_SET_ATTRIBUTES_FLAGS</event>
 <rank>10</rank>
 <callback>evtSetAttributeFlags</callback>
 </event_listener>
 </event_listeners>
 <methods>
 <method id="evtSetInitialFlags" _delta="define">
 <static>false</static>
 <access>public </access>
 <comment>此方法在打开服务器创建表单之前调用一次</comment>
 <code><![CDATA[

public function evtSetInitialAttributeFlags(Combodo\iTop\Service\Events\EventData $oEventData)
{ // 强制标志，忽略现有标志
 $this->ForceInitialAttributeFlags('location_id', OPT_ATT_HIDDEN);
 // $this->AddInitialAttributeFlags('location_id', OPT_ATT_HIDDEN); 如果其他代码也强制将其设为必填，可能不起作用
}

public function evtSetAttributeFlags(Combodo\iTop\Service\Events\EventData $oEventData)
{
 if ((MetaModel::IsValidAttCode(get_class($this), 'status')) && ($this->Get('status') == 'production'))
 { // 添加必填标志
 $this->AddAttributeFlags('location_id', OPT_ATT_MANDATORY);
 // 可以决定设置此标志并忽略已为该属性设置的其他标志
 // 在这种情况下，使用 ForceAttributeFlags 代替 AddAttributeFlags
 $this->ForceAttributeFlags('location_id', OPT_ATT_MANDATORY);
 }
}

仅生产环境中的服务器和网络设备

将上述事件和方法分别在 Server 和 NetworkDevice 类上声明两次。

仅生产环境中的数据中心设备

将上述事件和方法在 DatacenterDevice 类上声明，而不是 Server 类。

提交时检查

我们也可以在提交时检查是否提供了位置，如果没有，则阻止创建/修改并显示错误消息，以便用户填写位置后再次提交。

订阅 EVENT_DB_CHECK_TO_WRITE 事件，并定义对象类的回调方法 evtCheckToWrite()：

此事件在写入数据库之前生成
如果遇到数据不一致，回调方法应提供错误消息。错误消息使用 $this->AddCheckIssue('Some Error Message') 生成，警告消息使用 $this->AddCheckWarning('Some Warning Message')
从此方法返回时，如果至少有一个错误，对象不会写入数据库（创建或更新）
错误和警告消息仅在交互模式下显示给用户：控制台、门户、CSV 导入
对于数据同步、REST/JSON、CLI，根据跟踪级别记录在 itop/log/error.log 中

迁移注意： 在设置上没有可见效果，但不符合规范的对象不能再被修改，直到它们变得合规。因此可能会阻止数据同步或 REST/JSON 脚本更新其他字段。要识别有问题的对象，请创建一个审计规则来检索不符合此新约束的对象，并在 UI 中或通过 CSV 导入逐一修复。

在 iTop 3.1.0 之前，可以使用扩展性 API，将相同代码放入 iApplicationObjectExtension::OnCheckToWrite() 中。

在此用例中，我们希望阻止服务器在未提供位置的情况下被设置为 “production” 状态。

<class id="Server" _delta="must_exist">
 <event_listeners>
 <event_listener id="evtCheckToWrite" _delta="define">
 <event>EVENT_DB_CHECK_TO_WRITE</event>
 <rank>10</rank>
 <callback>evtCheckToWrite</callback>
 </event_listener>
 </event_listeners>

public function evtCheckToWrite(Combodo\iTop\Service\Events\EventData $oEventData)
{
 // 防御性编程，确保 'status' 是当前类上的现有字段
 // 然后检查条件：枚举值返回代码而非标签，因此我们测试代码
 if (MetaModel::IsValidAttCode(get_class($this), 'status')
 && ($this->Get('status') == 'production'))
 {
 // AttributeExternalKey 永远不会为 NULL，0 是空值时使用的值
 if (MetaModel::IsValidAttCode(get_class($this), 'location_id')
 && ($this->Get('location_id') == 0))
 {
 // 'Server:Error:LocationMandatoryInProduction' 必须声明为字典条目
 $this->AddCheckIssue(Dict::Format('Server:Error:LocationMandatoryInProduction'));
 }
 }
}

也可以直接提供简单的纯文本错误消息：

$this->AddCheckIssue('Location is mandatory for all Servers in production');

在 XML 中定义字典条目的方式：

<entry id="Server:Error:LocationMandatoryInProduction" _delta="define">
 <![CDATA['Location is mandatory for all Servers in production']]>
</entry>

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:mandatory-field-on-condition

版本：3_2_0/customization/mandatory-field-on-condition.txt · Last modified: 2025/05/21 10:58 by 127.0.0.1

Docs: 仅对子类强制字段必填

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何仅在子类上强制字段必填。更多详细内容请参考 iTop 官方文档。

目标

此用例是强制提供字段的一种方式。

数据中心设备必填

在此用例中，我们希望 PhysicalDevice 类上声明的 location_id 字段仅在 DatacenterDevice 上必填。总结如下：

在 DatacenterDevice 下的所有类上位置必须必填：NAS、网络设备、SAN 交换机、服务器、存储系统、磁带库
在所有其他 PhysicalDevice 子类上位置保持可选，例如手机

注意： 在标准数据模型中，DatacenterDevice 是 PhysicalDevice 的子类之一，location_id 在 PhysicalDevice 上是可选字段。

此情况比较棘手，因为 iTop 数据模型不允许在子类上覆盖父类定义的属性。location_id 字段在 PhysicalDevice 类上声明，而 DatacenterDevice 是 PhysicalDevice 的子类。

<class id="DatacenterDevice">
 <fields>
 <field id="location_id">
 <is_null_allowed _delta="redefine">false</is_null_allowed>
 </field>
 </fields>
</class>

为解决此用例，我们必须订阅 2 个事件：一个用于"创建表单"，一个用于"修改表单"。

<class id="Server" _delta="must_exist">
 <event_listeners>
 <event_listener id="evtSetCreationFlags" _delta="define">
 <event>EVENT_DB_SET_INITIAL_ATTRIBUTES_FLAGS</event>
 <rank>10</rank>
 <callback>evtSetCreationFlags</callback>
 </event_listener>
 <event_listener id="evtSetModificationFlags" _delta="define">
 <event>EVENT_DB_SET_ATTRIBUTES_FLAGS</event>
 <rank>10</rank>
 <callback>evtSetModificationFlags</callback>
 </event_listener>
 </event_listeners>

我们在创建时强制要求提供位置，并在修改时阻止移除位置。位置仍可在对象修改表单中更改。

public function evtSetCreationFlags(Combodo\iTop\Service\Events\EventData $oEventData)
{ // 注意：创建时调用的方法与修改时不同
 $this->ForceInitialAttributeFlags('location_id', OPT_ATT_MANDATORY);
}
public function evtSetModificationFlags(Combodo\iTop\Service\Events\EventData $oEventData)
{ // 注意：修改时调用的方法与创建时不同
 $this->ForceAttributeFlags('location_id', OPT_ATT_MANDATORY);
}

迁移注意： 在设置上没有可见效果，但不符合规范的对象不能再在控制台或门户中修改，直到提供了位置。创建一个审计规则来检索不符合此新约束的对象并修复它们。

仅服务器和网络设备

在此用例中，我们希望 location_id 字段仅对 Server 和 NetworkDevice 必填，而对 PhysicalDevice 的其他子类不是必填。

解决方案与上述情况类似，只需在 PhysicalDevice 类上声明上述方法，并在每个 Server 和 NetworkDevice 类上订阅事件。

public function evtSetCreationFlags(Combodo\iTop\Service\Events\EventData $oEventData)
{
 $this->ForceInitialAttributeFlags('location_id', OPT_ATT_MANDATORY);
}
public function evtSetModificationFlags(Combodo\iTop\Service\Events\EventData $oEventData)
{
 $this->ForceAttributeFlags('location_id', OPT_ATT_MANDATORY);
}

<class id="Server">
 <event_listeners>
 <event_listener id="evtSetCreationFlags" _delta="define">
 <event>EVENT_DB_SET_INITIAL_ATTRIBUTES_FLAGS</event>
 <rank>10</rank>
 <callback>evtSetCreationFlags</callback>
 </event_listener>
 <event_listener id="evtSetModificationFlags" _delta="define">
 <event>EVENT_DB_SET_ATTRIBUTES_FLAGS</event>
 <rank>10</rank>
 <callback>evtSetModificationFlags</callback>
 </event_listener>
 </event_listeners>
</class>
<class id="NetworkDevice">
 <event_listeners>
 <event_listener id="evtSetCreationFlags" _delta="define">
 <event>EVENT_DB_SET_INITIAL_ATTRIBUTES_FLAGS</event>
 <rank>10</rank>
 <callback>evtSetCreationFlags</callback>
 </event_listener>
 <event_listener id="evtSetModificationFlags" _delta="define">
 <event>EVENT_DB_SET_ATTRIBUTES_FLAGS</event>
 <rank>10</rank>
 <callback>evtSetModificationFlags</callback>
 </event_listener>
 </event_listeners>
</class>

所有数据中心设备，但磁带库除外

此用例：我们希望 location_id 字段对所有 DatacenterDevice 必填，但磁带库除外。

解决方案与上述情况类似，只需在 DatacenterDevice 类上声明上述方法，并在函数中测试最终类是否不是 TapeLibrary。

以下是在 PHP 方法中获取和测试最终类值的方法：

if ($this->Get('finalclass') != 'TapeLibrary') { ...

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:mandatory-field-subclass

版本：3_2_0/customization/mandatory-field-subclass.txt · Last modified: 2025/05/21 10:59 by 127.0.0.1