升级到2.7.x

[annProg]

从 2.5 升级到目前的最新版 2.7.x，调研自 2.5 以来的变化

关注以下几点：

• 插件结构的变化
• 唯一性检查功能
• 新特性的使用场景
• 一些函数的变化

2.6： https://www.itophub.io/wiki/page?id=2_6_0%3Arelease%3A2_6_whats_new

[annProg]

插件开发方式变化

Since: 2.4

Ref: https://www.itophub.io/wiki/page?id=2_7_0%3Acustomization%3Adatamodel

区分 extension 和 module

扩展是一个或者多个模块组成的。

The concept of extension is introduced with iTop 2.4. An extension is an assembly of one or more module(s). 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.

目录中包含 extension.xml 文件，则被视为扩展。
当扩展只包含一个模块时，可以将 extension.xml 和其他模块文件放在一个目录里，即不需要多层目录。包含多个模块时，扩展根目录放 extension.xml 和 每个模块的目录。

如果一个模块被多个扩展使用，iTop 只会安装版本最高的那个（这样似乎会出现重复代码？）。

extension.xml

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.

只有一个模块的扩展是可以只分一层目录的，把 extension.xml 直接放到模块根目录，这种模块如果被另外一个扩展引用，即其父目录也会有一个 extension.xml 文件，这时，这种模块的 extension.xml 会被忽略。

一个例子

<?xml version="1.0" encoding="UTF-8"?>
<extension format="1.0">
	<extension_code>molkobain-datacenter-view</extension_code>
	<company>Molkobain</company>
	<author><![CDATA[Guillaume Lajarige]]></author>
	<label><![CDATA[Datacenter view]]></label>
	<description><![CDATA[Visual representation of racks, enclosures & devices]]></description>
	<version>1.7.0</version>
	<release_date>2020-06-14</release_date>
	<version_description><![CDATA[Add filter panel to highlight devices based on their name / serial number / asset number]]></version_description>
	<itop_version_min>2.4.0</itop_version_min>
	<status>stable</status>
	<mandatory>false</mandatory>
	<more_info_url>https://github.com/Molkobain/itop-datacenter-view</more_info_url>
</extension>

[annProg]

唯一性检查功能

Since: 2.6

通过 xml 定义唯一性规则，不需要在单独写 doCheckToWrite 函数了。文档地址：https://www.itophub.io/wiki/page?id=2_7_0%3Acustomization%3Auniqueness-rules

一个例子，要求FunctionalCI 下的对象如果属于同一个子类，则名字不能重复，否则可以重复，比如某个 NetworkDevice 和 Server 可以重名，但是两个 Server 或者 两个 NetworkDevice 不能重名，定义以下规则：

        <uniqueness_rules>
          <rule id="functionalci_name" _delta="define">
            <!-- field or combination of "FunctionalCI" fields which must be unique -->
            <attributes>
              <attribute id="name"/>
              <attribute id="finalclass"/>
            </attributes>
          <!-- ... -->

即 name 和 finalclass 这两个属性的组合需要是唯一的，因此就能实现不同的子类可以有相同的名字，相同的子类对象不能重名。

另外一个完整的例子，标准模型中的 Person 唯一性检查规则：

    <class id="Person" _delta="define">
      <parent>Contact</parent>
      <properties>
        ...
        <uniqueness_rules>
          <rule id="employee_number">
            <attributes>
              <attribute id="org_id"/>
              <attribute id="employee_number"/>
            </attributes>
            <filter><![CDATA[employee_number != '']]></filter>
            <disabled>false</disabled>
            <is_blocking>true</is_blocking>
          </rule>
          <rule id="name">
            <attributes>
              <attribute id="org_id"/>
              <attribute id="name"/>
              <attribute id="first_name"/>
            </attributes>
            <filter/>
            <disabled>false</disabled>
            <is_blocking>false</is_blocking>
          </rule>
        </uniqueness_rules>
      </properties>
      <fields>
	  ...

可以看到 uniqueness_rules 在 properties 下定义。这个规则限制每个组织下不能有相同员工号的 Person，id 为 name 的规则，is_blocking 为 false，表明这个规则不是强制的，只会给出警告，依然能更新成功。毕竟，同名的人挺常见的。
其中 filter 的含义是，过滤某些不关心的情况，比如这个例子中，employee_number 为空的情况并不关心，允许为空并且不认为是重复项，因此用 filter 字段把这种情况过滤掉。
以上文档还有一个 filter 的例子，用于父类中定义的规则不检查某些子类：

            <!-- Define an OQL WHERE clause with condition on FunctionalCI fields -->
            <!-- It will be combined this way "SELECT FunctionalCI WHERE " + <filter> -->
            <filter><![CDATA[
               finalclass NOT IN ('DBServer','Middleware',
              'OtherSoftware','WebServer','PCSoftware','MiddlewareInstance',
              'DatabaseSchema','ApplicationSolution')]]>
            </filter>

标准模型定义了以下规则

• Class Brand, field name must be unique.
• Class Model, fields: name + brand_id must be unique.
• Class Person, fields: org_id + employee_number must be unique only if employee_id is defined.
• Class Person, fields: org_id + first_name + name should be unique (warning only).

修改规则和修改其他属性是一样的方法。如：

<rule id="employee_number" _delta="delete"/>

[annProg]

Tag Attribute功能

Since: 2.6

新增了一个 AttributeTagSet 属性，用于给一个对象添加标签。可能可以作为多选的一种方案。
目前标准数据模型中只实现了 FAQ 的标签。需要开发插件实现自定义标签。

链接：https://www.itophub.io/wiki/page?id=2_6_0%3Afeature%3Atag

[annProg]

对象更新，对象删除触发器

Since: 2.6

新增了对象更新和对象删除触发器，不需要单独插件了，需要测试是否兼容以前使用的插件的功能。

兼容性

• TriggerOnUpdate 不支持 exclude_code，需要确认是否有影响。原插件经过定制支持 exclude_code。

注意

xx_list 类型的属性可以被 TriggerOnUpdate 跟踪，但只能在对应对象里，如果编辑了其 lnk 类，或者编辑的是 lnk 类另一端的对象，虽然都会引起 xx_list 的变化，但并不会触发 TriggerOnUpdate。

Be aware that if you set a TriggerOnUpdate on class Team for field members_list,

• the trigger will occur only if the list of members is modified from the Team object
• On the opposite, if you edit a person and add or remove it from the Team, the above trigger will not be activated, also the members_list was modified.
• If a DataSynchro or a CSV import load directly objects lnkPersonToTeam, again the trigger will not be activated, unless the load of lnkPersonToTeam is done through a synchro/import of Team

取值

• As for every Trigger, when you specify a filter you can use :this→attribute_code and it contains the value after the change.
• In the filter of a TriggerOnDelete the values of the current object can still be tested

TriggerOnUpdate 其他注意事项

• 省略跟踪属性时任何变更都会触发
• 多个属性是任意一个属性变更都会触发，但是如果两个属性都变更了，只会触发一次
• 可用于 Caselog 但是不建议这么用，应该用更专业的触发器比如 TriggerOnLogUpdate, TriggerOnEmailUpdate 等
• 当使用 TriggerOnUpdate 时应在配置文件中设置 email_asynchronous=true，as a CSV import, a bulk update can generate a lot of emails and impact the performances

[annProg]

函数变化

Since: 2.7

跟踪对象变化，或者变化前的值

• \iApplicationObjectExtension::OnDBUpdate
• \DBObject::AfterUpdate

MetaModel::GetObject

这时一个很常用的函数，影响会比较大。

// before 2.7.0 this was working for non admin users
$oUser = MetaModel::GetObject('User', $iCurrentUserId);
 
// After 2.7.0 to search for objects of the User class 
// You need to explicitly specify to ignore current user rights on the User class
// Forcing the 4st parameter to true, bypass "current user rights"
$oUser = MetaModel::GetObject('User', $iCurrentUserId, true, true); 

函数定义

public static GetObject($sClass, $iKey, $bMustBeFound = true, $bAllowAllData = false, $aModifierProperties = null)

DBSearch::AllowAllData

itop-request-template 中用到了。

// before 2.7.0 this was working for non admin users
$oFilter = DBSearch::FromOQL('SELECT User WHERE id = :id');
$oSet = new DBObjectSet($oFilter, array(), array('id' => $iCurrentUserId));
$oCurrentUser = $oSet->Fetch();
 
// After 2.7.0 you should add this to get Users objects
// Despite current user doesn't have rights on the User class :
$oFilter = DBSearch::FromOQL('SELECT User WHERE id = :id');
$oFilter->AllowAllData(); // this method call will bypass user access rights
$oSet = new DBObjectSet($oFilter, array(), array('id' => $iCurrentUserId));
$oCurrentUser = $oSet->Fetch();

函数定义： https://www.itophub.io/wiki/page?id=2_7_0%3Acustomization%3Aapi%3Aobjects-manipulation%3Adbsearch#allowalldata

[annProg]

Dashboard Attribute

Since: 2.6

AttributeDashboard 给对象详情页增加一个 Dashboard. 比如给组织对象增加一个显示本组织资源和工单情况的 Dashboard。

[annProg]

API变化

Since: 2.6.1

Core/Get 分页支持 supports two new parameters :

limit (int): Amount of results to return (default: 0 = no limit)
page (int): Page number to return (cannot be < 1)
Example :

{
   "operation": "core/get",
   "class": "Person",
   "key": "SELECT Person",
   "output_fields": "friendlyname, email"
   "limit": "5",
   "page": "2"
}

[annProg]

test-red 主题

Since: 2.7

一个帮助区分测试环境和生产环境的主题，看起来挺有用。配置文件中指定：

    // This line should be added on the iTop test instance only
    'backoffice_default_theme' => 'test-red',

[annProg]

iTop Markup

Since: 2.7

通过此功能可以修改 console 或者 portal 里一些项目的样式，比如高亮某个属性。在 Kubernetes 插件中，有高亮 Deployment 的状态，可以考虑用此功能重做。

文档见：https://www.itophub.io/wiki/page?id=2_7_0%3Afeature%3Amarkup#itop_markup

[annProg]

代码高亮

Since: 2.7

在 描述 或者 caselog 里加入高亮的代码。

[annProg]

密码策略

Since: 2.7

可以为 authent-local 用户定义密码策略，默认策略要求 8+ 字符，包含大小写字母，数字和特殊字符。可以通过以下配置移除默认策略：

      'authent-local' => array (
                'password_validation.pattern' => '',
        ),

文档：https://www.itophub.io/wiki/page?id=2_7_0%3Aadmin%3Apassword-policy

[annProg]

认证API

Since: 2.7

Starting with version 2.7.0, it is now much easier to add new authentication methods in order to connect to iTop.

Some are new 2.7 possibilities which must be coded using the iTop authentication API:

• SAML (45 parameters)
• OAuth/openID (Facebook, Twitter, GitHub, Google… +27 existing applications)
• Multiserver LDAP

后续调研，基于最新 API 写一个 OIDC 登录的插件。

文档：https://www.itophub.io/wiki/page?id=2_7_0%3Acustomization%3Aauthentication

[annProg]

OQL NOT IN SELECT

Since: 2.7

举例，查询 Teams without members

SELECT Team WHERE id NOT IN (SELECT Team AS t JOIN lnkPersonToTeam AS l ON l.team_id=t.id)

文档：https://www.itophub.io/wiki/page?id=2_7_0%3Aoql%3Aoql_examples#oqlnew_in_27

[annProg]

基于上下文的提醒功能

Since: 2.7

可根据引起触发的模块（CRON，REST，Console，Portal）来决定是否发送提醒。

文档：https://www.itophub.io/wiki/page?id=2_7_0%3Aadmin%3Anotifications#creating_a_trigger

[annProg]

基于console界面的升降级操作

Since: 2.7

With iTop 2.7.0 and above, iTop administrators can upgrade or downgrade their iTop, directly from iTop web interface (console), without having access to the iTop server.

文档: https://www.itophub.io/wiki/page?id=2_7_0%3Aadmin%3Acore-update