iTopCN – iTop 集成

Docs: 数据同步概述

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

数据同步允许将 iTop 对象与外部数据源（如 CSV 文件、LDAP 目录、数据库等）对齐。同步是单向的：从外部数据源到 iTop。

如果不熟悉此功能，请先阅读本概述，然后参考数据同步参考了解详细配置。

联邦化多个数据源

强大的数据同步引擎允许将来自多个信息源的数据（例如使用网络发现工具或资产管理工具时）联邦到 iTop 中。

使用数据源对象进行联邦化

这种联邦化在 iTop 中通过数据源对象来定义。每个数据源定义了 iTop 如何处理来自特定源的特定类型对象的同步。

同步数据的通用流程

同步数据的通用（持续）流程基于以下步骤：

提取数据 — 从外部源/应用程序提取数据 [不由 iTop 处理]
转换数据 — 将数据转换为适合 iTop 的内容/格式 [不由 iTop 处理]
导入数据 — 使用 MySQL 命令将数据导入 iTop 中的副本表 [不由 iTop 处理]
搜索匹配对象 — 在 iTop 中搜索匹配对象 [由 iTop 处理]
创建/更新或删除 — 在 iTop 中创建/更新或删除同步对象 [由 iTop 处理]
显示和管理 — 在 iTop 中显示和管理同步对象

此流程可以通过两种方式执行：

方式一：数据直接写入数据库

以下是从外部源到 iTop 的信息流示例，使用 ETL 直接将数据写入 MySQL。

在 iTop 中实现数据同步

要在 iTop 中实现数据同步，请按照以下步骤操作：

从 iTop 管理菜单中，为要导入/同步的对象类型定义一个数据源对象。这会创建一个特定的副本表在 iTop 数据库中，名为 synchro_data_xxx。（创建数据源后，检查数据源的属性选项卡。临时表的名称显示在顶部。）
使用您喜欢的 ETL 工具或普通脚本，将来自外部源的数据填充到对应数据源的 synchro_data_xxxx 表中。您可以使用特殊列 primary_key 来存储对象在外部应用程序中的任何标识符。此表中的每条记录将对应 iTop 中的一个对象。id 列保留给 iTop 使用，不能写入。所有其他列对应于 iTop 对象的字段。
通过执行页面 synchro/synchro_exec.php 来触发 iTop 对象与临时表副本之间的数据同步，可以在命令行模式下执行，或通过调用网页（例如使用 wget）来执行。

当然，您可以定期安排上述步骤 2 和 3（每小时、每天或每周）。

有关更多信息，请参阅副本。

方式二：通过 CSV 文件导入数据

另一种方法是创建一个中间 CSV 文件，并使用 iTop 提供的 PHP 脚本 synchro_import.php 执行到 MySQL 的导入。

在这种情况下，信息流如下所示：

提取数据 — 从外部源/应用程序提取数据 [不由 iTop 处理]
转换数据 — 将数据转换为适合 iTop 的内容/格式 [不由 iTop 处理]
写入数据 — 将数据写入中间 CSV 文件 [不由 iTop 处理]
导入数据 — 将数据导入 iTop 中的副本表 [由 iTop 处理]
搜索匹配对象 — 在 iTop 中搜索匹配对象 [由 iTop 处理]
创建/更新或删除 — 在 iTop 中创建/更新或删除同步对象 [由 iTop 处理]
显示和管理 — 在 iTop 中显示和管理同步对象

CSV 导入与数据同步的区别是什么？

数据同步

数据同步旨在以定期方式从另一个系统导入数据到 iTop。它可以从命令行或 Web 运行，但不能交互式运行。数据同步针对大量不经常变化的数据进行了优化。例如，LDAP 服务器中的 10,000 个联系人可以每天同步到 iTop 一次。不太可能每天有超过一小部分用户记录被修改。iTop 可以高效地处理这种情况。

同步数据时，iTop 会跟踪 iTop 对象与数据源之间的关系。因此，可以阻止用户在 iTop 中修改同步对象（部分或全部），并告知他们数据来源。这对于在 iTop 中"联邦化"多个数据源非常有用。

CSV 导入

CSV 导入可以交互式运行或从命令行运行。它更针对"一次性"导入。它可以从脚本（使用命令行界面或从 Web）或交互式使用。执行 CSV 导入时，iTop 不会记录有关数据来源的信息。数据加载到 iTop 后，授权用户可以修改对象，无需引用原始源。

总结

CSV 导入适用于：

将初始数据导入 iTop
对数据执行批量转换（有时导出 > 在 Excel 中修改 > 重新导入，比直接在 iTop 中编辑对象更容易）

数据同步适用于：

在 iTop 中联邦化不同系统之间的数据
通过某种计划机制导入数据
阻止用户修改导入的数据

同步的配置项

当配置项与数据源同步时，其在 iTop 中的显示会略有不同。对 CI 的操作也可能受到限制，具体取决于数据源的配置。

例如，对象中同步的字段可能对最终用户显示为只读。还可以配置 iTop 以阻止用户删除同步对象。同步 CI 的确切行为由每个数据源的属性决定。

（注意对象标题中的"锁"图标及其附加的工具提示）。

附加复杂性

设计

此机制在设计时考虑了以下约束：

针对每天同步大量数据进行优化
易于与第三方数据管理工具（如 Talend）集成
安全且易于操作/故障排除

设置和常见陷阱

由于这些要求，设置它并不像人们想象的那么直观。下面描述了常见的陷阱：

从同步数据表中删除记录

从同步数据表中删除记录不会删除对象。它只会将对象从同步机制中分离。用户将有权编辑或删除对象，就像它们是从 UI 中创建的一样。将对象重新附加到同步需要设置数据源以便可以进行协调，然后将记录重新引入同步数据表。同步机制将为您从同步数据表中删除记录。

定期重新创建完整的同步数据表

使用相关设置，这可以工作。但是，当表被清空时（直到它再次被填充并且同步再次运行），用户不会看到相应对象被视为同步。同步执行需要很长时间，并且会严重影响 iTop Web 服务器的响应时间。对于每个同步的项目，都必须进行协调，需要执行查询来搜索最佳匹配。

使用此机制进行实时同步

通过 REST/JSON 等 Web 服务实现这要容易得多。范式更直观：创建一个对象（分别更新/删除），然后调用 REST 操作"对象创建"（分别更新/删除）。

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

版本：3_2_0/advancedtopics/data_synchro_overview.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 中同步/更新以及可能删除对象的规则
同步对象对 iTop 最终用户的行为（哪些字段是只读的，是否允许用户删除对象等）
一个可选的超链接和图标，用于将 iTop 用户引导到外部应用程序中的相应对象

描述

属性部分的这一部分定义了此同步数据源的一些通用参数。

属性	必填？	含义	示例值
名称	必填	引用此数据源的名称	来自 SCCS 的服务器同步
描述	可选	附加描述，仅供参考
状态	必填	implementation、production 或 obsolete：用于过滤/分类数据源	production
目标类	必填	要同步的对象类	Server
用户	必填	允许执行此同步的用户	admin
通知联系人	可选	当同步执行完成且包含至少一个错误时，通过电子邮件通知的联系人
图标超链接	可选	指向代表此数据源的图像的超链接（URL）。此图标显示在 iTop 中同步对象标题旁"锁"符号的默认图标工具提示中
应用程序超链接	可选	指向同步数据来自的远程应用程序的超链接（URL）。超链接可以包含占位符，如 $this->attcode$ （将被当前对象的属性值替换）或 $replica->column_name$ （将被副本中命名列的值替换）	`https://myapp.acme.com/display/server/$replica->primary_key$`
数据表	可选	存储副本信息的 MySQL 表名。如果省略，系统将为您生成一个唯一名称	synchro_data_servers_from_sccs

搜索与协调

属性的这一部分定义了：

副本表中的信息如何与 iTop 数据库的内容匹配
此同步数据源关于创建新 iTop 对象的行为

属性	含义
协调策略	使用属性（use_attributes）：创建新副本时，系统将根据设置了"协调"标志为"是"的同步属性列表在 iTop 中搜索匹配对象。使用主键（use_primary_key）：副本的 `primary_key` 列预期包含 iTop 中对象的标识符。
零个匹配时的操作	协调在 iTop 中未找到任何对象时的操作。创建（Create）指示系统创建目标类的新对象。错误（Error）将导致系统将此情况报告为错误（即此同步数据源应仅更新现有对象）。
一个匹配时的操作	协调在 iTop 中找到一个匹配对象时的操作。更新（Update）指示系统更新此对象。错误（Error）将导致系统将此情况报告为错误（即此同步数据源应创建对象且从不更新现有对象）。
多个匹配时的操作	协调在 iTop 中找到多个匹配对象时的操作。创建（Create）指示系统创建另一个对象。错误（Error）将导致系统将此情况报告为错误。取第一个（Take the first one）指示系统选择列表中的第一个对象并更新它。

删除规则

此部分定义同步对象的删除处理方式：

由 iTop 中的最终用户删除
由同步系统本身删除

属性	含义
允许删除的用户	哪些最终用户可以在 iTop 中删除同步对象。无人（Nobody）：对象同步后，无人可以在 iTop 中删除它，只有同步系统可以删除它。仅管理员（Administrators only）：只有管理员可以删除同步对象。允许删除此类对象的所有人（Everybody allowed to delete such objects）：正常的访问规则适用于此类同步对象。
全量加载间隔	两次被认为是已加载（触及）所有副本的同步执行之间的持续时间。当副本在超过此值的时间内未被触及时，它被视为过时。
删除策略	副本变为过时时执行的操作。忽略（Ignore）：不执行任何操作，关联对象保持原样。删除（Delete）：在 iTop 中删除关联对象（以及数据表中的副本）。更新（Update）：按照下面的更新规则更新关联对象。更新后删除（Update then Delete）：按照下面的更新规则更新关联对象，然后在保留持续时间后删除对象（及副本）。
更新规则	以分号分隔的值列表，格式为 `attribute_code:value`，用于指定关联对象的哪个属性设置为哪个值。示例：`status:obsolete;description:no longer synchronized`
保留持续时间	仅在删除策略设置为"更新后删除"时使用。在这种情况下，从源中删除的对象会立即更新，并且仅在保留持续时间后才从 iTop 中删除。

如果设置全量加载间隔为 7 天，保留持续时间为 14 天，则不再由源提供的对象将在 3 周后被删除。

属性

“属性"选项卡定义：

如何确定是否必须在 iTop 中创建新对象，或者是否必须将现有对象与副本关联（如果协调规则为属性中的"使用属性”）
关联对象的哪些属性必须更新，以及如何更新

属性选项卡	用途
属性	自动列出数据同步"目标类"的每个属性，及其标签和代码
协调	指定此列中的值是否应用于检索现有的 iTop 对象。仅用于新副本
更新	指定该 iTop 对象属性是否应由数据同步更新
更新策略	指定该属性是否可以在 iTop 中编辑
协调键	仅适用于外部键属性。指定用于检索远程对象的一个属性。可以是 id 或作为远程类唯一标识符的字段

协调列

当新记录出现在 synchro_data_xxx 表中时，同步机制将尝试将此记录与现有的 iTop 对象关联。如果一个或多个属性在"协调？“列中标记为"是”，这些列/属性将用于搜索匹配所有这些值的 iTop 对象。如果找到一个对象，它将成为与此记录关联的对象。如果未找到对象，将创建一个新的 iTop 对象。

更新列

更新列定义属性是否必须更新。

选中 = 是：属性将被设置/更新
未选中 = 否：此属性的外部源信息将被忽略，iTop 对象上的现有值将保持不变
Null ⇒ 保留现有的 iTop 字段值
空字符串 ⇒ 重置 iTop 对象字段

您必须使用自己的填充机制将 Null 值加载到 synchro_data_xxx 表中，因为 synchro_import.php 无法做到这一点。

更新策略列

更新策略列定义了在编辑 iTop 对象时更新属性的行为。可能的值包括：

锁定（Locked）：属性将完全由数据同步驱动，在 iTop 用户界面中显示为只读（旁边有一个小锁图标）
解锁（Unlocked）：属性将由同步更新（每当源数据更改时），但最终用户仍可以在 iTop 中并行修改该属性
为空时初始化（Initialize if empty）：同步仅在该属性在 iTop 中的值为空时才设置值。该属性在 iTop 中保持可修改

协调键列

最后，协调键列定义如何处理引用另一个 iTop 对象的属性（即外键）。提供的数据可以包含外键的实际值（id）或另一个属性（如对象的名称），该属性必须唯一标识该对象。

状态

状态选项卡显示有关同步执行的信息。如果同步从未运行，选项卡显示以下消息：

This synchro was never run. No log yet.

否则，选项卡显示类似于下图的架构：

同步历史

在屏幕左侧，每次同步执行都显示在历史列表中，显示总体状态、执行的开始日期和时间。

单击此列表中的元素以在右侧两列中显示相应的状态详情。

左侧列显示 synchro_data_xxxx 表中记录的状态：

新记录（New）：自上次执行同步以来添加到表中的记录
现有记录（Existing）：之前已存在且自上次执行同步以来已再次加载的记录
消失记录（Disappeared）：在超过 full_load_interval 持续时间内未被加载的记录
忽略记录（Ignored）：对应于 iTop 中不再存在的对象

右侧列显示同步的后果，即对 iTop 中关联对象的修改。

对于每个新记录，后果可以是：在 iTop 中创建新对象（已创建）、更新 iTop 中已存在的对象（已更新）、与 iTop 中已是最新的对象简单关联（未更改），或尝试在 iTop 中创建或更新对象时出错（错误）
对于每个现有记录，后果可以是：更新关联对象（已更新）、完全无变化（未更改），或尝试更新关联对象时出错（错误）
对于每个消失记录，后果（取决于"删除规则"）可以是：在 iTop 中删除关联对象（已删除）、在 iTop 中更新关联对象（已更新）、在 iTop 中保持关联对象不变（无操作），或尝试在 iTop 中更新或删除关联对象时出错（错误）

副本

在 iTop 中，副本用于存储状态信息以及 synchro_data_xxx 表中加载的原始数据与关联 iTop 对象之间的关系。

可以通过单击状态选项卡顶部的链接来显示给定数据同步源的副本。副本显示如下：

副本的内容有助于理解数据同步机制的行为（并获取有关错误的更多信息），但其数据由同步维护，不应手动修改。

副本字段	用途
同步数据源	此副本所属的同步数据源
目标对象（ID）	对应于该副本的 iTop 对象 id。当副本是新的且由于错误无法同步时，可以为空
目标类型	同步数据源的目标类，也是目标对象的类
状态	副本的状态：已修改、新建、过时、孤儿、已同步
最后出现	该副本在源数据中最后一次出现的时间（相同的 `primary_key`）
对象已创建？	数据同步是否创建了 iTop 对象？
最后错误	错误
警告	发生某些非阻塞错误时的警告消息
创建日期	同步数据源创建 iTop 对象的时间
最后修改日期	该副本最后一次被源修改的时间

副本状态	含义
新建（New）	新接收的副本。在 `syncho_exec.php` 发生以创建 iTop 对象之前的临时状态
已修改（Modified）	修改的副本。在 `syncho_exec.php` 发生以更新 iTop 对象之前的临时状态
已同步（Synchronized）	副本和 iTop 对象已对齐
过时（Obsolete）	数据中不再在源中，iTop 对象未被删除，否则副本也会被删除
孤儿（Orphan）	这不应该发生。在这种情况下，同步的 iTop 对象已消失，同时未删除副本。此类副本可以安全地手动删除

使用 MySQL 语句填充 synchro_data_xxxx 表

如果您使用 SQL 命令（使用 ETL 或自制脚本）填充 synchro_data_xxx 表，您必须注意永远不要创建重复记录。请记住，synchro_data_xxx 表中的每条记录恰好对应 iTop 中的一个对象。

为了避免此类重复，您必须首先在插入新记录到表中之前查询现有记录。为了加速此查询，您可以构造一个唯一标识"源"对象的值并将此值存储在表的 “primary_key” 列中（该列具有唯一索引），或者使用记录列的任何组合并更改 synchro_data_xxxx 表的定义以添加您自己的索引。

然后触发 iTop 对象与临时表副本之间的数据同步执行，通过执行页面 synchro/synchro_exec.php，可以在命令行模式下执行，或通过调用网页（例如使用 wget）来执行。

使用 synchro_import 填充 synchro_data_xxxx 表

请参阅：synchro_import.php

如何指定相关对象列表（链接集）

某些类具有称为链接集的属性。示例：UserLocal.profile_list

您可以通过在相应列中写入所有信息来同步这些列表：

以下是指定登录将具有一个配置文件：‘Portal User’ 的示例

INSERT login, profile_list INTO data_synchro_userlocal_1 VALUES ('johndoe', 'profileid->name:Portal User;reason:Customer')...;

您还可以指定多个链接（多个配置文件）。

有关更多信息，请参阅导入链接集。

故障排除

请参阅数据同步故障排除

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

版本：3_2_0/advancedtopics/data_synchronization.txt · Last modified: 2024/10/28 12:21 by 127.0.0.1

Docs: 同步故障排除

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

数据同步过程中的常见问题及解决方法。

建议

选择 primary_key

使用每个值都唯一且稳定的 primary_key 至关重要。

确保永远不会有 2 个源对象共享相同的 primary_key 值。
确保源对象永远不会在源中修改其 primary_key。

primary_key 字段必须在源数据的单列中提供。如果要使用源字段的组合，请让源应用程序将它们连接成单个列。

协调属性

如何在源数据同步上选择协调属性：

如果源应用程序是该类的主控（iTop 中不能直接创建该类的对象），则使用 primary_key 进行协调，或者更准确地说，使用具有相同信息的列。将源应用程序的 primary_key 存储在 iTop 对象字段中可以大大简化未来的故障排除。在这种情况下，源数据必须在 2 个不同的列中复制 primary_key 列，第一个用作同步副本对象的 primary_key，另一个用于更新 iTop 对象字段。
否则，如果您选择可以在源中修改的 iTop 属性：这些协调属性必须由数据同步更新并锁定！仅当您确定它们在源中无法修改时才不需要。

内部处理

数据源导入

运行 synchro_import.php 或使用您自己的进程更新 synchro_data_xxx 表时，MySQL 会触发一些后台行为：

更新与 synchro_data_xxx 中每个更新行关联的 SynchroReplica 对象：status_last_seen = now，status = 'modified'
为 synchro_data_xxx 中每个创建的行创建 SynchroReplica 对象：status_last_seen = now，status = 'new'

同步数据

处理未看到的副本

对于以下副本：

SELECT SynchroReplica
WHERE sync_source_id = :source_id
 AND STATUS IN ('new', 'synchronized', 'modified', 'orphan')
 AND status_last_seen < (now – :full_load_interval)

更新 SynchroReplica：

status = 'obsolete'
如果删除策略 = “更新” 或 “更新后删除”：使用更新规则更新 iTop 对象，更新 SynchroReplica 的 info_last_modified = Now

处理新副本

对于每个状态为 ’new’ 的 SynchroReplica，我们在 iTop 中搜索与源行具有相同值的每个协调 = ‘yes’ 的数据同步属性的对象：

如果未找到对象（或多个匹配且"多个匹配时的操作" = “创建”）：我们创建一个新的 iTop 对象。如果创建成功，我们更新 SynchroReplica：info_creation_date = now，dest_id = 刚创建对象的 id，status_dest_creator = 'yes'，status = 'synchronized'。如果创建失败，我们更新 SynchroReplica：status_last_error = 失败创建的错误消息
如果找到一个对象（或多个匹配且"多个匹配时的操作" = “取第一个”）：更新 SynchroReplica：dest_id = 检索到的对象的 id，status_dest_creator = 'no'，status = 'synchronized'。更新 iTop 关联对象。如果成功，更新 SynchroReplica 的 info_last_modified = now。如果失败，更新 SynchroReplica 的 status_last_warning = 失败更新的错误消息
如果找到多个对象且"多个匹配时的操作" = “错误”：更新 SynchroReplica 的 status_last_warning = "n 个目标对象匹配协调条件：xxxxxxxx"

处理更新的副本

对于每个状态为 “modified” 的 SynchroReplica：

更新 iTop 关联对象。如果成功，更新 SynchroReplica：info_last_modified = now，status = 'synchronized'。如果失败，更新 SynchroReplica：status_last_warning = 失败更新的错误消息

处理过时的副本

对于每个应该应用删除策略的 ‘obsolete’ 副本：

SELECT SynchroReplica
WHERE sync_source_id = :source_id
 AND STATUS IN ('obsolete')
 AND status_last_seen < (now _ :retention_delay)

如果删除策略 = “更新” 或 “更新后删除”：删除 iTop 对象，删除对应的 SynchroReplica(s)，删除 synchro_data_xxx 表中对应的行

常见问题

非唯一 primary_key

如果源中多个对象共享相同的 primary_key，您将遇到严重麻烦。这些具有相同 primary_key 的各种对象都将更新同一个 iTop 对象。该 iTop 对象将在每次源对象更改时发生变化，而您不会理解原因。

非稳定 primary_key

为源数据选择的 primary_key 必须是稳定的，对于任何给定对象都永远不会改变。

为什么 primary_key 不能在源中更改？

假设您有一个数据同步，用于 Person，其中您在源中提供了 primary_key（人员的电子邮件），但将协调键设置为：name + firstname + org_id。

您运行第一次同步：在源中，我们有一行 primary_key 为 smith@biz.com 的记录。此行创建一个新的 SynchroReplica，然后创建或更新一个具有该电子邮件的 iTop Person：Alex Smith。
稍后，在您的源应用程序中，人员的电子邮件由于某种原因从 smith@biz.com 更改为 alex.smith@biz.com，并启动同步：由于电子邮件是源的 ‘primary_key’，该新电子邮件在 synchro_data_xxx 源表中显示为新行，因此创建新的 SynchroReplica：alex.smith@biz.com。新的 SynchroReplica 映射到现有的 iTop Person：Alex Smith，并修改其电子邮件。旧的 SynchroReplica：smith@biz.com 不再在源中，并被标记为过时。它仍然映射到同一个 iTop Person：Alex Smith。
一些同步后，在删除策略过期延迟时：旧的过时 SynchroReplica：smith@biz.com 更新 iTop Person Alex Smith，例如将其状态设置为 inactive。与此同时，新的 SynchroReplica：alex.smith@biz.com 保持不变，因为源中没有任何变化，它不更新 iTop Person。
更多同步后，在保留持续时间过期时：旧的过时 SynchroReplica：smith@biz.com 删除 iTop Person Alex Smith。作为反作用，该删除同时删除了两个 SynchroReplica：smith@biz.com 和 alex.smith@biz.com。
随后的同步：重新创建 SynchroReplica：alex.smith@biz.com，并重新创建 iTop Person Alex Smith（假设数据同步可以创建 iTop 对象）。但之前 Alex Smith 的所有关系都丢失了，他创建的工单、他的团队等等…

如果已经选择了错误的 primary_key 怎么办？

如果您已经使用 Person 电子邮件设置了数据同步，但后来注意到这是一个问题，因为您公司的电子邮件地址不稳定，并且正在产生上述问题。那么您考虑使用源应用程序 Person Id，这在您的世界中是一个稳定的值。它可能是稳定的，因为该源应用程序是处理您公司人员的主应用程序，每个新人员都在那里创建，每个更改都在那里进行。无论电子邮件更改、姓氏更改或组织更改如何，人员 id 都保持不变。

在这种情况下，创建一个新的数据同步源并删除前一个。

旧数据同步创建的对象不会被标记为由新数据同步创建，
因此这将防止数据同步删除对象。

未检索到的 ExternalKey

尝试使用包含提供的源信息的协调键字段检索远程 iTop 对象时，该搜索可能会失败，要么是因为没有匹配的对象，要么是因为有多个匹配的对象。如果 ExternalKey 是同步对象的必填字段，这将生成错误，否则只是警告，ExternalKey 将被清空。

Could not find [unique] object for 'manager_id': searched on friendlyname = 'Bob Smith'

无效的枚举值

如果对于同步对象的枚举属性，源提供了无效值，例如 “空字符串”，这永远不是有效的枚举值，那么根据枚举属性是否为必填项，您将获得警告或错误。

Unable to update destination object: Unexpected value for attribute 'status': Null not allowed:
issues = {0=>Unexpected value for attribute 'status': Null not allowed}, class = Person, id = 14

大多数副本变为过时

如果您的数据同步突然似乎使所有副本都过时了，可能的根本原因是同步表上的 SQL 触发器不再存在。

对表的不同命令可以删除它们，
数据库的备份/恢复也可能丢失它们，如果执行备份的用户没有足够的权限。

要检查 MySQL 触发器是否仍然存在，请运行此 MySQL 命令：

show triggers like '%synchro_data_xxx%';

其中 synchro_data_xxx 是您的数据同步表的名称。

每个 synchro_data 表应该有 3 个触发器。如果它们消失了，请参阅下面的提示来修复。

提示

恢复 MySQL 触发器

如果触发器丢失，可以通过重新保存数据源来重新创建它们。在 iTop 中打开数据源，点击"修改"，然后直接点击"应用"（无需进行任何更改）。这将触发 iTop 重新创建缺失的触发器。

删除数据同步

不建议删除数据同步并从头创建一个新的，特别是如果您的数据同步预期会删除 iTop 对象（现在或将来），因为此功能将会丢失。新的数据同步不会删除您在重新创建数据同步当天 iTop 中已经存在的对象。

如果不是这种情况，没有重大后果，只是在删除和新创建的同步上执行 synchro_import 之间的期间，某些用户可能已经修改了 iTop 对象，因为它们不再被锁定，对于同步锁定的字段，他们的更改将被覆盖，因此没有数据问题，只是用户体验有些奇怪…

DELETE FROM priv_sync_datasource WHERE id= x;
DELETE FROM priv_sync_replica where sync_source_id=x;
DELETE FROM priv_sync_log where sync_source_id=x;
DELETE FROM priv_sync_att_linkset where sync_source_id=x;
DELETE FROM priv_sync_att_extkey where sync_source_id=x;
DELETE FROM priv_sync_att where sync_source_id=x;
DROP table synchro_data_xxx;

原文：https://www.itophub.io/wiki/page?id=3_2_0:advancedtopics:data_synchronization-troubleshooting

版本：3_2_0/advancedtopics/data_synchronization-troubleshooting.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 导出数据 (export-v2.php)

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

iTop 提供通用的 Web 服务 export-v2.php，基于 OQL 查询导出数据，用于与第三方工具集成。支持格式：HTML、CSV、XML、Spreadsheet、XLSX、PDF

调用方式

命令行

php /var/www/itop/webservices/export-v2.php --auth_user=login --auth_pwd=password --expression="SELECT Server" --format=csv --fields=name,brand,model

远程 HTTP

# Basic 认证
wget --http-user=login --http-password=password "http://itopserver/webservices/export-v2.php?expression=SELECT+Server&format=csv"

# Token 认证
wget --post-data='--auth-token=YOURTOKEN' "http://itopserver/webservices/export-v2.php?expression=SELECT+Server&format=csv"

参数

参数	描述	默认值
param_file	参数文件	-
expression	OQL 查询	与 query 二选一
query	查询手册中保存的查询 ID	与 expression 二选一
format	`html`/`csv`/`xml`/`spreadsheet`/`xlsx`/`pdf`	html
fields	逗号分隔的属性列表（支持 `caller_id->org_id->code`）	类的所有属性
with_archive	`1` 包含归档对象	0
arg_xxx	OQL 参数 xxx 的值	无

输出字段顺序遵循 fields 参数中的顺序。扩展属性码可能显著降低导出速度。

输出格式

HTML

HTML 格式将输出作为 HTML 表格提供。

Spreadsheet

推荐用于 Excel Web 查询集成。

参数	描述	默认值
date_format	日期格式	同 GUI
formatted_text	导出富文本标记	1
no_localize	使用内部代码和值	0

XML

参数	描述	默认值
linksets	`1` 检索关联对象	0
no_localize	使用内部代码和值	0

XML 格式忽略 fields 参数，始终检索所有字段。

XML 输出示例：

<?xml version="1.0" encoding="UTF-8"?>
<Set>
 <Server alias="Server" id="1">
 <name>Server1</name>
 <description></description>
 <org_id>3</org_id>
 <org_id_friendlyname>Demo</org_id_friendlyname>
 <organization_name>Demo</organization_name>
 <status>production</status>
 ...
 </Server>
</Set>

CSV

参数	描述	默认值
charset	字符编码	UTF-8
separator	分隔符	,
text-qualifier	文本限定符	"
date_format	日期格式	同 GUI
formatted_text	导出富文本标记	0
no_localize	使用内部代码和值	0

CSV 示例：

id,Name,Management IP
1,"dbserver1.demo.com","10.1.1.10"
6,"webserver.demo.com","10.1.1.20"

XLSX

参数	描述	默认值
date_format	日期格式	同 GUI
formatted_text	导出富文本标记	0

PDF

参数	描述	默认值
date_format	日期格式	同 GUI
page_size	A3/A4/Letter	A4
page_orientation	Landscape/Portrait	Portrait

PDF 适合 <10 列，列多时建议 Landscape。

权限要求

门户用户不允许访问此服务
用户必须在指定类上有 bulk read 权限

历史版本

0.9：首次实现此功能
1.2.1：添加参数 query，作为 expression 的替代
1.2.1：添加格式 spreadsheet，拆分日期和时间列
2.0：添加标志 no_localize
2.1.0：添加 XLSX 格式
2.2.0：通过创建新的 export-v2.php 页面重新设计导出功能

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

版本：3_2_0/advancedtopics/exportdata.txt · Last modified: 2026/03/10 13:11 by 127.0.0.1

Docs: CLI 数据导入

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

iTop 提供命令行工具 import.php，通过 CSV 文件批量导入数据。

用途

iTop 提供了一个通用的 Web 服务，用于基于源 CSV 文件将数据导入 iTop。此服务可以在服务器上通过命令行界面本地使用，也可以通过 HTTP POST 请求远程使用。

使用此服务，您可以轻松地通过批处理脚本将数据导入 iTop，该脚本从第三方工具提取数据并生成 CSV 格式文件。例如，一个从 Active Directory 提取联系人列表的脚本。

当需要导入真正大量的数据时，CLI 模式是必须的，因为您不会达到 Web 服务器的限制（超时和内存限制）。

用法

命令行界面

命令行的所有参数都在后面的“参数”部分列出。以下行是必填参数的示例。所有参数都以 -- 开头。

php /var/www/itop/webservices/import.php --auth_user=login --auth_pwd=password --class=Organization --csvfile=file --reconciliationkeys="list of keys"

协调键对于唯一标识要导入到 iTop 的元素非常重要。协调键必须存在于数据文件中。与交互式 CSV 导入不同，您不限于类定义的默认协调键列表。

此外，外部键将通过协调方案中指定的所有属性来唯一标识。在我们的示例中，如果您认为 Name/Country 唯一标识位置，则在协调方案中同时使用 Location->Name 和 Location->Country。

参数

参数	描述	默认值
param_file	参数文件	-
auth_user	用户登录名 - 仅限 CLI 模式	-
auth_pwd	用户密码 - 仅限 CLI 模式	-
class	加载对象的类	必填！
csvdata	CSV 内容（仅限 HTTP 模式，数据可以通过此页面参数发布）	HTTP 模式下必填
csvfile	源文件的路径和名称	CLI 模式下必填
charset	CSV 数据的字符集编码：UTF-8、ISO-8859-1、WINDOWS-1251、WINDOWS-1252、ISO-8859-15	使用 iTop 配置文件中的 `csv_file_default_charset`，默认值为 ‘ISO-8859-1’
date_format	输入日期格式（用于日期和日期时间）- 示例：Y-m-d、d/m/Y（法国）	<空白>
separator	CSV 数据中的列分隔符	,（逗号）
qualifier	CSV 数据中的文本限定符	“（双引号）
output	`retcode` 返回错误行数，`summary` 返回简洁报告，`details` 获取详细报告（列出每一行）	summary
reconciliationkeys	用于标识现有对象并更新它们或创建新对象的列标签或代码（取决于 `no_localize` 标志）（逗号分隔）	<空白>
simulate	如果设置为 1，则加载不会执行，但会生成预期报告	0
with_archive	如果设置为 1，则导入将检索归档对象作为要更新的对象和有效的外部键	0
comment	要添加到变更日志中的注释	<空白>
no_localize	如果设置为 0，则列标题、值和协调键应使用登录用户的语言进行本地化。设置为 1 以使用内部属性代码和值（枚举）	0 = 标签不区分大小写

输出

命令行将返回一个摘要报告（见下文），总结导入使用的参数和导入结果：

创建的元素数量
更新的元素数量
出错的元素数量

如果您为 output 参数指定了 details 选项，您将获得每个导入元素的一行及其导入状态（见下面的示例）。

php /var/www/itop/webservices/import.php --auth_user=login --auth_pwd=password --class=Organization --csvfile=file --reconciliationkeys="list of keys" --output=details

结果

#Output format: details
#Class: Organization
#Separator: ;
#Qualifier: \"
#Charset Encoding:UTF-8
#Data Size: 26
#Data Lines: 1
#Simulate: 0
#Columns: name, code
#Reconciliation Keys: name
#Change tracking comment:
#Issues: 0
#Warnings: 0
#Created: 1
#Updated: 0
#Unchanged: 0
Line;Status;Object Class;Object Id;name (Name);code (Code)
0;created;Organization;3;\"WorldCompany\";\"WCY\"

可能的错误

缺少参数

ERROR: Missing argument 'class'

当缺少必填参数时显示此错误。

错误的参数

#Unknown class: 'toto'

如果指定的类在 iTop 中不存在，则会发生此错误。请注意类名区分大小写。

#Unknown reconciliationkeys: 'attribute'

如果协调键列表中至少有一列未知，则会发生此错误。原因可能是：

提供了代码而不是标签，或反之亦然
协调键是外部字段
协调键不在 csv 文件中

#Unknown column: 'Last Nme'

如果 csv 文件中的列未知，则会发生此错误。

允许的用户

管理员始终被允许执行此页面。

非管理员如果被允许修改给定类的对象，则将被允许执行。

导入图像和文件

某些类在其字段中包含图像或文件文档。例如，Person 类包含一个 Picture 字段，用于保存该人员的照片。交互式编辑 Person 时，用户可以从她的计算机上传图像以提供该人员的照片。但是，在执行 CSV 导入时，无法“上传”此类文件或将其内容放入 CSV 文件本身，因为 CSV 格式不支持此操作。

在这种情况下，CSV 文件必须在适当的 CSV 列中提供一个 URL 来上传文件。此 URL 必须可以从 iTop 服务器访问，并返回预期的图像（或文件文档）。如果上传失败或上传文档的格式与字段的预期格式不匹配（例如，如果 URL 没有为 picture 字段返回图像），则此字段的导入/更新将失败（并且 CSV 的整行将被拒绝）。

URL 必须直接指向要上传的图像（不支持重定向）
URL 必须可以从 iTop Web 服务器访问（注意某些公共网站可能会拒绝访问 PHP 脚本 - 它们会检查 HTTP User Agent 字符串）
URL 不需要身份验证，因为上传是由 iTop 服务器本身完成的
指向 iTop 本身的 URL（如 CSV/Excel 导出提供的 URL）是支持的。但仅当它们指向同一个 iTop 实例时（在这种情况下，导入将解析提供的 URL 并从 iTop 数据库中读取文档）
如果您使用管理员账户执行 CSV 导入，您可以指定位于 iTop 服务器本身的文件路径（但这仅适用于管理员）

引用已存储在 iTop 中另一个对象上的图像的示例。使用的语法：https://<your-itop>/pages/ajax.document.php?operation=download_document&class=<ObjectClass>&id=<ObjectId>&field=<FieldCode>

用例：将人员及其对应的登录导入 iTop

此用例描述如何将人员和他们的登录导入 iTop。这是从 Active Directory 加载这些信息的一种方式。在这种情况下，您只需编写一个脚本，从 Active Directory 创建两个 csv 文件 person.csv 和 login.csv。

导入人员

我们想创建两个联系人：

属于组织 Demo 的 Claude Monet
属于组织 IT Department 的 Gustave Flaubert

在此示例中，两个组织已存在于 iTop 中。

要导入的类是 Person，csv 文件（login.csv）中的数据为：

Last Name,Status,Organization->Name,Email,Phone,Notification,Function,First Name
"Monet","Active","Demo","monet@demo.com","","yes","","Claude"
"Flaubert","Active","IT Department","flaubert@it.com","","yes","","Gustave"

然后运行以下命令行：

php webservices/import.php --auth_user=admin --auth_pwd=admin --csvfile="person.csv" --class="Person" --reconciliationkeys="Email"

导入用户账户

我们想创建两个用户账户：

support 是配置经理和变更主管，与联系人 flaubert@it.com 相关
portal 是与联系人 monet@demo.com 相关的门户用户

在此示例中，登录通过电子邮件与联系人关联，我们导入与联系人关联的配置文件。查看导入配置文件的特定语法。有关导入链接集的更多信息，请参阅导入链接集。

要导入的类是 UserLocal：

Person->Email,Login,Language,Password,Profiles
"flaubert@it.com","support","EN US",1234,profileid->name:Configuration Manager|profileid->name:Change Supervisor
"monet@demo.com","portal","EN US",1234,profileid->name:Portal user

然后运行以下命令行：

php webservices/import.php --auth_user=login--auth_pwd=password --csvfile="login.csv" --class="UserLocal" --reconcialiationkeys="Login"

导入允许的组织示例：

假设我想为同一个用户允许 3 个组织。
源文件中的每个组织可以通过其 id、name 或 code 来标识。
加载像 Allowed Organizations 这样的 AttributeLinkedSetIndirect 时，预期的字段是 n:n 关系类的字段（此处 URP_UserOrg），这意味着您只能提供 allowed_org_id。
但通常，对于 n:n 关系，您了解远程对象的一些字段值，但可能不知道它的 iTop id。在这种情况下，您可以指定远程对象的代码，并且有一种特殊的语法：
- 关系类中的 ExternalKey，指向远程对象（例如 allowed_org_id）
- 一个破折号字符后跟一个大于号：->
- 远程属性的代码（例如 name）
- 一个冒号：
- 检索远程对象的值（例如 Demo）
- 一个管道符，用于分隔需要链接到同一个用户的 2 个远程对象
- 以及上述 5 个步骤的重复

像这样 "allowed_org_id->name:Demo|allowed_org_id->code:IT"

在此示例中，我结合了不同的方式来标识同一用户的 n:n 关系中的组织，这有效，但您可能不会每天都使用它。

Person->Email,Login,Language,Password,Profiles,Allowed Organizations
"monet@demo.com","portal","EN US",1234,"profileid->name:Portal user","allowed_org_id->code:IT|allowed_org_id->name:Demo|allowed_org_id:1"

导入位置

"name","org_id->name","country","city"
"Bordeaux","Demo","France","Bordeaux"
"Grenoble","Demo","France","Eybens"
"Paris","Demo","France",""

然后运行以下命令行：

php webservices/import.php --auth_user=login --auth_pwd=password --csvfile="location.csv" --charset="UTF-8" --no_localize=1 --class="Location" --reconcialiationkeys="name,org_id->name"

限制 / 已知问题

外部字段（如 virtualhost_id->org_name）不能用作协调键。
- 解决方法：org_name 可以替换为 org_id->name
限制：箭头运算符（->）不能多次使用（即 virtualhost_id->org_id->name 不受支持）。

历史版本

0.9：首次实现此功能
2.0：添加标志 no_localize

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

版本：3_2_0/advancedtopics/importcli.txt · Last modified: 2025/04/29 16:27 by 127.0.0.1

Docs: REST/JSON API

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

iTop 提供 REST/JSON API，允许外部应用通过 HTTP 请求对 iTop 对象进行增删改查操作。

介绍

iTop 提供了一个 REST/JSON 接口，允许第三方应用程序远程与 iTop 交互以检索、创建或更新 iTop 对象。此接口基于一组简单的 HTTP POST 请求。传递给 iTop 和从 iTop 检索的数据使用 UTF-8 字符集以 JSON 编码。

此类请求可以从任何能够发出 HTTP/POST 并操作 JSON 编码数据的编程语言执行。请求甚至可以直接在 javascript 中从任何网页运行，通过跨站点脚本（iTop 支持 CORS 和 JSON-P）。

您还可以在 Postman 上找到完整的文档。

用于 POST 请求的 URL 如下：

<itop-root>/webservices/rest.php?version=1.3

此类请求需要传递以下参数：

auth_user（可选，取决于登录模式）
auth_pwd（可选，取决于登录模式）
auth_token：如果要使用应用程序令牌或个人令牌，作为 auth_user 和 auth_pwd 的替代
json_data

实际上，HTTP 方法可以是 POST 或 GET（这是 JSON-P 支持所需的）。出于安全原因（避免以明文传递凭据）和 GET 对输入数据大小施加限制的原因，建议使用 POST 和 HTTPS。支持 HTTP 基本身份验证。

谁可以访问：

由于 REST Web 服务很容易被放入循环中，用户必须对他们修改的类具有写入访问权限和批量写入权限。应用刺激是一种修改。
确保使用 REST Web 服务的脚本具有 REST 服务用户 配置文件。
具有 管理员 配置文件的用户不会在没有此额外 REST 服务用户 配置文件的情况下访问 REST。

如果要模拟以前的行为（即允许任何用户访问 REST Web 服务），请添加配置参数 secure_rest_services 并将其设置为 false。

参数

参数	描述	默认值
version	API 版本。这是确保目标 iTop 服务器可以提供某些功能的一种方式，并且它确保您的脚本的稳定性：只要版本可用，操作将保持不变，但以下情况除外：错误修复、返回消息中的修改、返回的 JSON 结构中的新元素。	-
auth_user	用户登录名	-
auth_pwd	用户密码	-
auth_token	应用程序或个人令牌
json_data	包含 JSON 格式请求操作的字符串。或（3.0 中的新功能）`@<path>`，其中您提供带有路径的 JSON 操作文件，用于 CLI 执行
callback	如果设置，则使用 JSON-P（JSON with padding）

这些参数适用于任何类型的请求操作。

认证

请参阅如何认证到 Web 服务以选择相关的认证模式并相应地调整 HTTP 请求。

通过浏览器测试 API 可以完成，但在这种情况下，您必须调整 allowed_login_types 以在 iTop 的配置文件中启用 url。

PHP 数组形式的参数

自 2.7.1 和 3.0.0 起，参数可以使用 PHP 数组语法发送：

auth_user=my_user&auth_pwd=my_password&json_data%5Boperation%5D=core%2Fget&json_data%5Bclass%5D=ServiceChange&json_data%5Bkey%5D=SELECT+ServiceChange+WHERE+id%3D1&json_data%5Boutput_fields%5D=request_state

文件中的参数

自 3.0.0 起，为了测试，您可以将 JSON 操作写入文件以进行 CLI 执行：

{
 "operation":"core/create",
 "comment":"Synchronization from blah...",
 "class":"UserRequest",
 "output_fields":"id, friendlyname",
 "fields":
 {
 "org_id":"SELECT Organization WHERE name = 'Demo'",
 "caller_id":{"name":"monet","first_name":"claude"},
 "title":"issue blah",
 "description":"something happened"
 }
}

然后您可以使用以下 Curl 命令在命令行界面上执行此操作（必须启用 formlogin_type）：

curl -X POST -F 'version=1.3' -F 'auth_user=admin' -F 'auth_pwd=admin' https://localhost/itop/webservices/rest.php -F 'json_data=@./my-json-operation.json'

curl -X POST -F 'version=1.3' --header 'authorization: basic YWRtaW46YWRtaW4=' https://localhost/itop/webservices/rest.php -F 'json_data=@./my-json-operation.json'

# YWRtaW46YWRtaW4= 对应于字符串 login:password 的 base64 编码

curl -X POST -F 'version=1.3' -F 'auth_token=YOURTOKEN' https://localhost/itop/webservices/rest.php -F 'json_data=@./my-json-operation.json'

如果使用最后一个示例，您需要在 allowed_login_type 参数中激活 login_mode 令牌。

操作：list_operations

您应该熟悉的第一个操作是：list_operations。此命令返回所有可能的操作列表。

json_data 输入的语法尽可能简单：

{
 "operation": "list_operations"
}

回复将如下所示：

{
 "version": "1.2",
 "operations":
 [
 {
 "verb": "core/create",
 "description": "Create an object",
 "extension": "CoreServices"
 },
 {
 "verb": "core/update",
 "description": "Update an object",
 "extension": "CoreServices"
 },
 {
 "verb": "core/get",
 "description": "Search for objects",
 "extension": "CoreServices"
 }
 ],
 "code": 0,
 "message": "Operations: 3"
}

请注意以下部分：

{
 "code": 0,
 "message": "Everything went well"
}

…是所有由 rest.php 提供的服务共有的，返回的其他信息取决于请求的操作。

错误代码

错误代码在 applicationextension.inc.php 中可用，作为 RestResult 类的常量：

值	常量	含义
0	OK	未遇到任何问题
1	UNAUTHORIZED	缺少/错误的凭据或用户没有足够的权限执行请求的操作
2	MISSING_VERSION	缺少参数 ‘version’
3	MISSING_JSON	缺少参数 ‘json_data’
4	INVALID_JSON	输入结构不是有效的 JSON 字符串
5	MISSING_AUTH_USER	缺少参数 ‘auth_user’
6	MISSING_AUTH_PWD	缺少参数 ‘auth_pwd’ 或您正在使用 url 登录类型，而它在 iTop 的配置文件中未被允许
10	UNSUPPORTED_VERSION	没有可用于指定版本的操作
11	UNKNOWN_OPERATION	请求的操作对指定版本无效
12	UNSAFE	无法执行请求的操作，因为它可能导致数据（完整性）丢失
100	INTERNAL_ERROR	无法执行操作，请参阅消息进行故障排除

核心服务

核心服务是通用服务。它们等同于 iTop 核心 PHP API：DBObject、DBObjectSearch 和 DBObjectSet。

使用这些服务，您可以操作任何类型的数据，前提是您了解足够的类和属性信息。

如何指定键

键是标识对象的一种方式。这种类型的规范可用于确定操作的目标对象，并用于确定外部键（或"外键"）的值。

允许三种形式：

指定对象的 id（作为数字）：

...
 "key": 123

指定搜索查询（OQL）：

...
 "key": "SELECT UserRequest WHERE caller_name LIKE \"monnet\""

指定搜索条件（所有条件都使用 AND 运算符组合）：

...
 "key":
 {
 "name": "Monnet",
 "first_name": "Claude"
 }

如何指定值

属性的值以取决于属性类型的格式给出。

以下是一个说明某些情况的示例：

 "name": "Monnet",
 "first_name": "Claude",
 "age": 80,
 "picture": {
 "data": "iVBORw0KGgoAAAAN.......AAAAElFTkSuQmCC",
 "filename": "smiley.png",
 "mimetype": "image/png"
 }

标量

对于大多数属性类型，值只是一个标量。

对于外部键，值是一个键（见上面的定义）。

对于格式化为纯文本的文本字段，新行通过 “\n” 指定。

示例：

"name": "Monnet",
"description": "A famous french artist.\nLaunched the impressionism trend."
"presentation": "<p>A famous french artist</p><p>Launched the <em>impressionism</em> trend.</p>"
"age": 80,
"org_id": "SELECT Organization WHERE name = 'Demo'",
"location_id": 3,
"supervisor_id":
{
 "name": "Foo",
 "first_name": "John"
}

二进制数据（Blobs）

对于 Blobs（即二进制数据），值以包含三个项目的数组形式给出：data、filename 和 mimetype。

‘data’ 是经过 base64 编码的二进制数据
‘filename’ 是原始文件的名称。其目的是在文件被进一步下载时提供默认文件名。
‘mimetype’ 必须与文件格式匹配，以便 iTop 可以正确显示它。

示例：

"picture": {
 "data": "iVBORw0KGgoAAAANSUhEUgAAAA8AAAAPCAIAAAC0tAIdAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACmSURBVChTfZHRDYMwDESzQ2fqhHx3C3ao+MkW/WlnaFxfzk7sEnE6JHJ+NgaKZN2zLHVN2ssfkae0Da7FQ5PRk/ve4Hcx19Ie6CEGuh/6vMgNhwanHVUNbt73lUDbYJ+6pg8b3+m2RehsVPdMXyvQY+OVkB+Rrv64lUjb3nq+aCA6v4leRqtfaIgimr53atBy9PlfUhoh3fFCNDmErv9FWR6ylBL5AREbmHBnFj5lAAAAAElFTkSuQmCC",
 "filename": "smiley.png",
 "mimetype": "image/png"
}

案例日志（Case Log）

自 iTop 2.0.3 起，有 3 种可能的语法用于填充"CaseLog"字段：简写语法、单一项或整个日志。

简写语法

如果提供简单的文本字符串，文本将作为案例日志中的新条目添加，使用当前日期和时间以及当前用户，并且文本将被隐式视为以 HTML 格式设置。

示例：

"public_log": "blah blah blah",

富语法

如果提供带有名为 add_item 的条目的结构，可以指定附加信息：

用户名（默认为用于 REST/JSON API 的凭据）
条目的日期/时间（默认为"现在"）
注释的格式（默认为"html"，可以设置为"text"）

示例：

"public_log": {
 "add_item":
 {
 "date": "yyyy-mm-dd hh:mm:ss",
 "user_login": "jfoo",
 "message": "The first line\nAnother line",
 "format":"text"
 }
},

完整语法

如果提供名为 items 的数组，则案例日志的整个内容将被提供的条目替换。

示例：

"public_log":
{
 "items":
 [
 {
 "date": "yyyy-mm-dd hh:mm:ss",
 "user_login": "jfoo",
 "message": "<p>The first line</p><p>A second line</p>"
 },
 {
 "date": "yyyy-mm-dd hh:mm:ss",
 "user_login": "jfoo",
 "message": "<p>The first line</p><p>A second line</p>",
 "format": "html"
 },
 {
 "date": "yyyy-mm-dd hh:mm:ss",
 "user_login": "jfoo",
 "message": "blah blah blah",
 "format": "text"
 }
 ]
},

链接集

对于链接集，值是一个对象定义数组。

示例：

"contacts_list":
[
 {
 "role": "artist",
 "contact_id":
 {
 "finalclass": "Person",
 "name": "monet",
 "first_name": "claude"
 }
 },
 {
 "role": "Basket-ball",
 "contact_id": "SELECT Team WHERE name = 'San Antonio Spurs'"
 },
 {
 "contact_id": 1234
 }
]

响应格式

core/… 操作的响应格式如下：

{
 "objects":
 {
 "objectclass::objectkey":
 {
 ...
 }
 },
 "code": 0,
 "message": "Found: 1"
}

其中每个对象的形式为：

 {
 "code": 0,
 "message": "",
 "class": "Person",
 "key": 1234,
 "fields": {
 "id": 1234,
 "name": "My last name",
 "status": "Active",
 "org_id": 123,
 .....
 .....
 .....
 }
 }

如果没有要返回的对象，您将得到：

"objects": null

可以通过 output_fields 参数（如果可用）控制给出的属性列表。output_fields 参数可以具有以下形式：

以逗号分隔的属性代码列表（例如：“name, status, org_id”）。只能给出查询类的属性。
* 表示查询类的所有属性
*+（自 2.0.3 起）表示每个找到的所有属性（子类可能比查询类具有更多属性）

操作：core/get

搜索对象列表。

示例：

传递以下 json_data：

{
 "operation": "core/get",
 "class": "Person",
 "key": "SELECT Person WHERE email LIKE '%.com'",
 "output_fields": "friendlyname, email"
}

或者，使用另一种形式的 “key”：

{
 "operation": "core/get",
 "class": "Person",
 "key": 1,
 "output_fields": "*"
}

自 2.6.1（PR #25，感谢 Dennis Lassiter！）起，使用两个新参数处理分页：

limit（整数）：要返回的结果数量（默认：0 = 无限制）
page（整数）：要返回的页码（不能 < 1）

记录排序可以使用 classes/class/properties/order 数据模型 XML 节点控制。

示例：

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

操作：core/create

创建给定类的新对象。

传递以下 json_data：

{
 "operation": "core/create",
 "comment": "Synchronization from blah...",
 "class": "UserRequest",
 "output_fields": "id, friendlyname",
 "fields":
 {
 "org_id": "SELECT Organization WHERE name = \"Demo\"",
 "caller_id":
 {
 "name": "monet",
 "first_name": "claude"
 },
 "title": "Houston, got a problem!",
 "description": "The fridge is empty"
 }
}

… 将导致创建一个新的用户请求。

某些属性具有特殊格式：

链接集：目前仅支持间接链接集，请参阅上面给出的示例
Blobs：文档内容（例如 DocumentFile/file）必须采用 {data: base64-encoded-data, mimetype: …, filename: …} 的形式
案例日志：允许三种形式。传递字符串等同于从 GUI 中添加新消息：消息代表当前用户（用于调用 Web 服务的凭据）记录。传递形式为 {add_item: {message: 'blah', user_id: 123, date:'2012-02-28 10:30'}} 的结构也会添加单条消息。user_id 和 date 是可选的，分别默认为当前用户和当前日期时间。指定 user_id 要求用于调用服务的凭据具有管理员权限，否则操作将失败并返回 UNAUTHORIZED 错误代码。传递形式为 {items: [ {message: 'blah'} ]} 的结构将设置整个日志。

响应示例：

{
 "code": 0,
 "message": "",
 "objects":
 {
 "UserRequest::123":
 {
 "code": 0,
 "message": "created",
 "class": "UserRequest",
 "key": 29,
 "fields":
 {
 "id": 29,
 "friendlyname": "R-000029"
 }
 }
 }
}

操作：core/update

更新一个对象。

传递以下 json_data：

{
 "operation": "core/update",
 "comment": "Synchronization from blah...",
 "class": "UserRequest",
 "key":
 {
 "description": "The fridge is empty"
 },
 "output_fields": "friendlyname, title, contacts_list",
 "fields":
 {
 "contacts_list":
 [
 {
 "role": "pizza delivery",
 "contact_id":
 {
 "finalclass": "Person",
 "name": "monet",
 "first_name": "claude"
 }
 }
 ]
 }
}

… 将通过将联系人列表设置为一个联系人（Claude Monet）和角色 ‘pizza delivery’ 来更新用户请求（通过其描述 “The fridge is empty” 标识）。

操作：core/apply_stimulus

更新一个对象并应用刺激以更改对象的状态。

传递以下 json_data：

{
 "operation": "core/apply_stimulus",
 "comment": "Synchronization from blah...",
 "class": "UserRequest",
 "key": 15,
 "stimulus": "ev_assign",
 "output_fields": "friendlyname, title, status, contacts_list",
 "fields":
 {
 "team_id": 18,
 "agent_id": 57
 }
}

… 将通过设置 agent_id 和 team_id 字段（对于状态 assigned 是必填的）来更新用户请求（通过其键 “15” 标识），然后应用刺激 ev_assign，使工单从状态 new 转换到状态 assigned。

操作：core/delete

删除一组对象。

传递以下 json_data：

{
 "operation": "core/delete",
 "comment": "Cleanup for customer Demo",
 "class": "UserRequest",
 "key":
 {
 "org_id": 2
 },
 "simulate": false
}

… 将删除客户 #2 的用户请求。

每个报告的对象都有一个删除状态代码和一个提供附加信息的消息。状态代码在 core/restservices.class.inc.php 中定义，作为 RestDelete 类的常量：

值	常量	含义
0	OK	根据初始请求删除对象
1	ISSUE	一般问题（用户权限或…？）
2	AUTO_DELETE	必须删除以保留数据库完整性
3	AUTO_DELETE_ISSUE	必须删除以保留数据库完整性，但不可能
4	REQUEST_EXPLICITELY	必须删除以保留数据库完整性，但必须显式请求
5	AUTO_UPDATE	必须更新以保留数据库完整性
6	AUTO_UPDATE_ISSUE	必须更新以保留数据库完整性，但不可能

操作：core/get_related

搜索相关对象。

给定一个对象或对象列表，搜索其他受这些对象影响或影响这些对象的对象。

传递以下 json_data：

{
 "operation": "core/get_related",
 "class": "Server",
 "key": 1,
 "relation": "impacts",
 "depth": 4,
 "redundancy": true,
 "direction": "down"
}

… 将搜索 Server::1 影响的所有 CI。搜索深度限制为 4 次迭代（默认为 20）。

结果将如下所示：

{
 "objects":
 {
 "objectclass::objectkey":
 {
 ...
 }
 },
 "relations":
 {
 "origin-class::origin-key":
 [
 {
 "key": "destination-class::destination-key"
 }
 ]
 },
 "code": 0,
 "message": "Scope: 1; Found: Server=4, VirtualMachine=3, Farm=1"
}

操作：core/check_credentials

检查用户登录名 + 密码。

传递以下 json_data：

{
 "operation": "core/check_credentials",
 "user": "john",
 "password": "abc123"
}

… 将回复（如果一切顺利）…

{
 "code": 0,
 "message": "",
 "authorized": true
}

示例和游乐场

如果您已经安装了 iTop（版本 2.0.1+），则可以点击此处测试 REST API。

以下是如何集成 REST/JSON 调用的示例：使用 bash 和 wget

使用配置文件创建用户

当创建对象需要 n:n 关系时，该对象的创建必须包括链接对象的创建。这在 iTop 标准数据模型中很少见，但它仍然存在于创建 User 对象时。

使用的语法有点棘手，因为链接创建不能提供 userid：

{
 "operation": "core/create",
 "comment": "Created",
 "class": "UserLocal",
 "output_fields": "id",
 "fields": {
 "contactid": 169,
 "login": "MyUser123",
 "password": "123456",
 "language": "EN US",
 "status": "enabled",
 "profile_list": [{"profileid": "MyProfileID"}]
 }
}

管理附件

请参阅使用 REST/JSON 管理对象附件。

管理内联图像

通过 REST/JSON 添加内联图像

如何添加服务

可以通过开发声明类（包含在您的自定义模块中）实现接口 iRestServiceProvider 的模块（或扩展）来扩展服务。

一旦您的模块安装完毕，您的自定义服务将可用，并与 operation=list_operations 一起列出。

变更历史

iTop 版本	JSON REST 版本	变更
2.0.1	1.0	创建
2.0.2	1.1	向返回的对象信息添加 ‘key’（在 1.0 中需要一些解析），将对象搜索条件转换为严格搜索（而不是松散搜索：包含…），允许重置外部键（设置为 0，表示"未定义"）
2.0.3	1.2	完全处理案例日志（可以完全读取或写入），枚举/GET 给出原始值而不是本地化标签，允许 HTTP 基本认证方法，添加动词 core/check_credentials，改进错误报告（缺少认证参数、写入链接集的错误类），添加选项 `*+` 以输出对象的所有字段（不仅仅是查询类的字段），修复对象删除报告
2.2.0	1.3	动词 get_related：添加选项 redundancy 和 direction 以考虑影响分析中的冗余。出于安全原因，现在禁止使用具有 Portal User 配置文件的用户账户使用 REST/JSON Web 服务。如果您仅使用其中一个 Web 服务来检查用户的凭据，请调整您的代码以使用 core/check_credentials 操作。出于安全原因，core/get 和 core/get_related 操作现在仅允许对指定类对象具有批量读取权限的用户。
2.5.2, 2.6.1, 2.7.0	1.4	动词 core/get：添加分页参数 limit 和 page

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

版本：3_2_0/advancedtopics/rest_json.txt · Last modified: 2024/12/11 19:02 by 127.0.0.1

Docs: REST/JSON 附件操作

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

通过 REST/JSON API 可以上传和下载 iTop 对象的附件。

添加附件

使用 REST/JSON Web 服务，附件只能与现有对象关联（即已记录在数据库中的对象）。如果要创建带有附件的工单，请先创建工单，然后创建附件对象。

使用 core/create REST 操作创建新的 Attachment 时，必须填写以下字段：

item_class：（字符串）此附件将关联到的对象类（例如 UserRequest）
item_id：（整数）此附件将关联到的对象的 ID
item_org_id：（整数）此附件将关联到的对象的组织 ID
creation_date：（字符串）当前日期和时间，MySQL 格式（例如 « 2021-04-30 12:23:41 »）
contents：包含 3 个元素的数组：
- data：（字符串）文件的 base64 编码二进制内容
- filename：（字符串）文件的名称（用于显示），例如 Untitled-1.docx
- mimetype：（字符串）文件的 MIME 类型，例如 application/vnd.openxmlformats-officedocument.wordprocessingml.document（对于 MSWord .docx 文档）

使用 core/create 操作创建 Attachment 对象：

{
 "operation": "core/create",
 "class": "Attachment",
 "fields": {
 "item_class": "Ticket",
 "item_id": 42,
 "item_org_id": 3,
 "creation_date": "2021-04-30 12:23:41",
 "contents": {
 "data": "base64编码的文件内容",
 "mimetype": "application/pdf",
 "filename": "document.pdf"
 }
 }
}

参数说明：

字段	说明
`item_class`	附件所属对象的类名
`item_id`	附件所属对象的 ID
`item_org_id`	附件所属对象的组织 ID
`creation_date`	创建日期，MySQL 格式
`contents.data`	Base64 编码的文件内容
`contents.mimetype`	文件 MIME 类型
`contents.filename`	文件名

删除附件

附件可以像 iTop 中的任何其他对象一样删除，使用 core/delete REST/JSON 操作。附件关联到的目标对象不需要任何操作。

更新附件

即使可以使用 REST/JSON Web 服务更新 Attachment 对象，用户界面也不允许此操作，因此 iTop 可能假设附件是不可变的（例如在索引数据时）。因此，建议通过删除旧附件并创建新附件来模拟用户界面的行为。

限制

附件大小受 PHP upload_max_filesize 和 post_max_size 限制
上传用户必须对目标对象有写权限
支持的 MIME 类型通常没有严格限制，但建议仅上传常见文档类型

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

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

Docs: Nagios 集成

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

iTop 可以与 Nagios 监控系统集成，将监控状态信息同步到 iTop 的配置项中。

概述

通过此集成：

Nagios 告警将转换为 iTop 中的事件工单
Nagios 中设备的状态详细信息可以直接在 iTop 中查看（作为对象上的额外选项卡）

虽然 Nagios 的配置非常具体（命令定义、处理程序定义），但相同的原理可以应用于任何能够在接收到告警时运行命令行脚本的基于 Web 的监控工具。

将 Nagios 告警转换为 iTop 中的工单具有众多优势，例如：

工单可以从创建到解决进行跟踪
可以为工单分配 SLA 以确保及时解决
iTop 可以计算由于某个组件故障而导致的"受影响"基础设施。“受影响"的项目会自动添加到事件工单中
iTop 可以通知受事件影响的各种人员

自动化在 iTop 中创建事件工单

本节描述如何配置 Nagios 以自动在 iTop 中创建事件工单。由于 Nagios “命令"基于命令行脚本，因此编写了一个特殊的 PHP 脚本，该脚本包装了 iTop 的 SOAP Web 服务，用于从命令行创建事件工单。请注意，由于 Nagios 调用的命令行脚本使用 SOAP Web 服务在 iTop 中创建工单，因此 Nagios 和 iTop 可以安装在不同的服务器上，前提是 Nagios 服务器到 iTop 之间可以进行 HTTP(S) 连接。

此脚本称为 “createTicket-nagios.php”。可以从这里下载：https://www.combodo.com/documentation/createTicket-nagios.zip

将此脚本复制到 Nagios 服务器上的目录中（例如 /etc/nagios3），并将文件 ‘itopsoaptypes.inc.php’ 从 iTop 实例的 ‘webservices’ 目录复制到同一目录中。

此脚本使用在 Nagios 中触发告警的主机的主机名来标识 iTop 中受影响的对象。因此主机名必须是唯一的。
脚本仅为处于 HARD 状态的 Nagios 告警触发工单。此外，它需要在 iTop 中预先配置默认工作组、默认呼叫者和默认客户。（有关工作组、呼叫者和客户的更多详细信息，请参阅 iTop 文档）
工单的严重程度始终相同，默认设置为严重。
此脚本只是描述如何使用 iTop SOAP Web 服务的示例。请根据您的需求随意改进。

用于工单创建的所有参数都列在脚本的开头，如下所示，必须根据您的配置进行调整。

<?php
// Adjust these settings to fit your iTop installation
// iTop Server location
define('ITOP_SERVER_URL', 'https://localhost/webservices/itop.wsdl.php');
// Valid credentials for connecting to iTop
define('ITOP_USERNAME', 'admin');
define('ITOP_PASSWORD', 'admin2');
// Default settings for creating the incident ticket
define('DEFAULT_IMPACT', 2); // 1 = department, 2 = service, 3 = person
define('DEFAULT_URGENCY', 2); // 1 = high, 2 = medium, 3 = low
define('DEFAULT_CALLER_NAME', 'Dali');
define('DEFAULT_ORGANIZATION_NAME', 'Demo');
define('DEFAULT_SERVICE_NAME', 'HW Monitoring');
define('DEFAULT_SERVICE_SUBCATEGORY', 'HW Troubleshooting');
define('DEFAULT_WORKGROUP_NAME', 'Hardware support');
// End of instance-specific parameters

在 Nagios 服务器上安装文件

步骤 1：将此脚本复制到以及 itopsoaptypes.class.inc.php
步骤 2：通过将以下内容添加到 Nagios 命令文件（大多数情况下称为 commands.cfg）来定义新的 Nagios 命令

# Create incident tickets in iTop command definition
define command{
command_name create-iTop-ticket
command_line <php path> <yourDirectory>/createTicket-nagios.php "$HOSTNAME$" "$SERVICEDESC$" "$SERVICESTATE$" "$SERVICESTATETYPE$" "$LONGSERVICEOUTPUT$"
}

其中是 PHP 的完整路径，<your_directory> 是您安装 iTop 脚本的路径。

您可以通过手动运行 PHP 脚本来测试工单创建。

步骤 3：对每个应该触发工单创建的主机或服务模板的事件处理程序选项中使用此命令：

您可以使用以下选项为所有主机和服务全局定义，这些选项大多在 nagios.cfg 中定义：

global_host_event_handler=create-iTop-ticket
global_service_event_handler= create-iTop-ticket

或者为每个主机和服务使用以下选项：

event_handler create-iTop-ticket
event_handler_enabled 1

如果您选择后者，则必须为您创建的每个主机和服务模板配置处理程序。

完成后，下次在 Nagios 中出现 HARD 告警时，它将自动在 iTop 中创建工单！

在 iTop 中查看 Nagios 状态

当在 iTop 中显示给定对象的详细信息时，浏览器框架中有多个选项卡。您可以创建一个新的选项卡，显示所选对象的 Nagios 框架。

修改 InfrastructureCI 类中的 DisplayBareRelations 函数
这将为所有非编辑模式下的生产环境 InfrastructureCI 添加 Nagios 选项卡。

function DisplayBareRelations(WebPage $oPage, $bEditMode = false)
{
 parent::DisplayBareRelations($oPage, $bEditMode);
 if (!$bEditMode)
 {
 $sStatus = $this->Get('status');
 $sName = $this->Get('name');
 if ($sStatus == 'production')
 {
 $oPage->SetCurrentTab(Dict::S('Nagios'));
 $oPage->add('<div id="checkmk" style="width:100%;height:500px;">');
 $oPage->add('<iframe style="border:0;padding:0;margin:0;width:100%;height:500px;overflow:auto" ');
 $oPage->add('src="https://<nagios_path>/cgi-bin/status.cgi?host='.$sName.'">');
 $oPage->add('</iframe></div>');
 }
 }
}

不要忘记将 “<nagios_path>” 设置为适合您安装的 URL。

注意，显示仅在您在 iTop 中使用的对象名称等于 Nagios 中对象的主机名时才有效。

完成后，保存文件并在浏览器中重新加载"详细信息"页面。

结果应该类似于下图：

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

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

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

Docs: 导入 LinkedSet

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

本文档介绍如何在 iTop 中导入 n:n 关联集合（LinkedSet）。更多详细内容请参考 iTop 官方文档。

什么是 LinkedSet？

LinkedSet 是一种表示相关对象列表的属性，在对象详情页中以标签页形式展示。LinkedSet 分为两种类型：

1:n — 例如"位置上的设备"：一台设备只能位于一个位置，而一个位置可以容纳多台设备。
n:n — 例如"团队的成员（人员）"：一个人可以属于多个团队，一个团队也由多名人员组成。

只有 n:n 类型的 LinkedSet 可以被导入。 你无法导入关联对象本身，它们必须已经存在于 iTop 中。

示例：UserLocal 具有属性 profile_list，该属性表示通过类 lnkUserProfile 附加到 UserLocal 对象上的权限列表。

何时可以导入关联集合？

以下所有数据输入功能都支持指定关联集合：

交互式 CSV 导入
命令行（CLI）导入
数据同步

示例：导入用户

以下示例展示如何在导入用户的同时，为其指定允许的组织（Allowed Organizations）和权限（Profiles）。这两个属性均为多对多关系：

假设需要为同一用户允许访问 3 个组织。
源文件中的每个组织可以通过其 id、name 或 code 来识别。
当加载类似"允许的组织"（Allowed Organizations）这样的 AttributeLinkedSetIndirect 时，所需字段来自 n:n 关系类（此处为 URP_UserOrg），这意味着你通常只能提供 allowed_org_id。
但一般情况下，对于 n:n 关系，你了解的可能是远程对象的某些字段值，而非其在 iTop 中的 id。此时，你可以使用远程对象的某个编码来指定，语法如下：
- 关系类中指向远程对象的外部键（如 allowed_org_id）
- 一个破折号后跟一个大于号：->
- 远程对象的属性编码（如 name）
- 一个冒号：:
- 用于检索远程对象的值（如 Demo）
- 一根竖线 |，用于分隔需要关联到同一用户的两个远程对象
- 重复上述步骤

完整格式如下：

allowed_org_id->name:Demo|allowed_org_id->code:IT

allowed_org_id->id:4 无效！
请改用 allowed_org_id:4

在此示例中，我们结合使用了不同的方式来识别同一用户的多对多关系中的组织。虽然这种方式可行，但日常使用中可能并不常见。

Person->Email,Login,Language,Password,Profiles,Allowed Organizations
"monet@demo.com","portal","EN US",1234,"profileid->name:Portal user","allowed_org_id->code:IT|allowed_org_id->name:Demo|allowed_org_id:1"

高级选项

假设需要为用户指定一组权限，并为每个权限注明授予原因。该"原因"字段属于多对多关系类。

首先，附加单个权限：

profileid->name:Configuration Manager

权限通过类 URP_UserProfile->profileid 进行关联。此处指定了类 URP_Profile 的属性 name 必须匹配 “Configuration Manager”。

现在，记录授予该权限的原因：

profileid->name:Configuration Manager;reason:operations manager

最后，为同一登录账号赋予另一个角色：

profileid->name:Configuration Manager;reason:operations manager|profileid->name:Change Supervisor

每个链接都是独立指定的。

每个新的链接规范都必须以 | 开头。

如果需要指定的原因中包含被解析为分隔符的字符，可以用引号将整个属性规范包裹起来：

profileid->name:Configuration Manager;reason:operations manager|profileid->name:Change Supervisor;'reason:manager ;-)'

限制与已知问题

无。

配置

在配置文件中，可以修改以下参数：

配置项	说明
`link_set_item_separator`	列表中两项之间的分隔符
`link_set_attribute_separator`	两个属性之间的分隔符
`link_set_value_separator`	属性名与值之间的分隔符
`link_set_attribute_qualifier`	整个属性的限定符

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

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

Docs: LDAP 人员同步

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

本指南演示如何从 LDAP 目录同步人员信息到 iTop。

先决条件

您需要：

了解如何从 LDAP 服务器提取人员信息并将其保存到 .CSV 文件
拥有一个 iTop 系统（安装了演示数据），并可以访问管理员账户
了解如何使用命令行连接到您的 iTop Web 服务器

本教程的目标

在本教程中，您将学习如何：

创建和配置用于将一类对象同步到 iTop 中的同步数据源
将外部数据输入并同步到此同步数据源
理解同步状态报告

分步说明

初始配置

在这里，您将创建同步数据源。

在管理工具菜单中，点击同步数据源。

点击创建新的同步数据源。

在以下屏幕中，在适当的字段中输入名称（来自 LDAP 的人员）、目标类（Person）和用户（admin）。

点击创建按钮以创建数据源。

数据源创建完成后，点击右上角的修改（铅笔）并编辑属性选项卡。

第一次同步：初始加载

然后在 iTop 根目录下的 “data” 目录中创建文本文件 “persons.csv”，内容如下：

primary_key;name;first_name;org_id;email;status;function;phone;notify
1;Monet;Claude;Demo;claude.monet@demo.com;Active;Manager;+33123456789;Yes
2;Flaubert;Gustave;IT Department;gustave.flaubert@demo.com;Active;;+33987654321;No

在 iTop 根目录中从命令行启动以下命令：

php synchro/synchro_import.php --auth_user=admin --auth_pwd=admin --csvfile=./data/persons.csv --data_source_id=1 --output=summary

auth_user：您的 iTop 登录名
auth_pwd：您的 iTop 密码
data_source_id：上面创建的同步数据源的标识符

预期输出：

#Load--------------
#------------------
#Data Source: 1
#Synchronize: 1
#Class: Person
#Separator: ;
#Qualifier: "
#Charset Encoding:UTF-8
#Date format: <none>
#Data Size: 228
#Data Lines: 2
#Columns: primary_key, name, first_name, org_id, email, status, function, phone, notify
#Output format: summary
#Simulate: 0
#Change tracking comment:
#Issues (before synchro): 0
#Created (before synchro): 2
#Updated (before synchro): 0
#Synchronization---
#------------------
#Replicas: 2
#Replicas touched since last synchro: 2
#Objects deleted: 0
#Objects deletion errors: 0
#Objects obsoleted: 0
#Objects obsolescence errors: 0
#Objects created: 0 (0 warnings)
#Objects creation errors: 0
#Objects updated: 0 (0 warnings)
#Objects update errors: 0
#Objects reconciled (updated): 2 (0 warnings)
#Objects reconciled (unchanged): 0 (0 warnings)
#Objects reconciliation errors: 0
#Replica disappeared, no action taken: 0

检查同步数据源的状态（如果需要，请按"刷新"图标）

您可以看到 2 个人员已更新。

导航到联系人 “Claude Monet” 的详细信息，您可以看到此对象现在已同步：

检查"活动面板"以查看最近的更改：

如果您尝试修改人员，您可以看到其大多数属性都被锁定：

第二次同步：更新联系人

修改文件 “persons.csv”，将 Claude Monet 的职能从 “Manager” 更改为 “Famous painter”。修改 iTop 根目录下 data 目录中的文本文件 “persons.csv”，内容如下：

primary_key;name;first_name;org_id;email;status;function;phone;notify
1;Monet;Claude;Demo;claude.monet@demo.com;Active;Famous painter;+33123456789;Yes
2;Flaubert;Gustave;IT Department;gustave.flaubert@demo.com;Active;;+33987654321;No

使用相同的命令再次启动导入和同步：

php synchro/synchro_import.php --auth_user=admin --auth_pwd=admin --csvfile=./data/persons.csv --data_source_id=1 --output=summary

输出如下：

#Load--------------
#------------------
#Data Source: 1
#Synchronize: 1
#Class: Person
#Separator: ;
#Qualifier: "
#Charset Encoding:UTF-8
#Date format: <none>
#Data Size: 235
#Data Lines: 2
#Columns: primary_key, name, first_name, org_id, email, status, function, phone, notify
#Output format: summary
#Simulate: 0
#Change tracking comment:
#Issues (before synchro): 0
#Created (before synchro): 0
#Updated (before synchro): 2
#Synchronization---
#------------------
#Replicas: 2
#Replicas touched since last synchro: 2
#Objects deleted: 0
#Objects deletion errors: 0
#Objects obsoleted: 0
#Objects obsolescence errors: 0
#Objects created: 0 (0 warnings)
#Objects creation errors: 0
#Objects updated: 1 (0 warnings)
#Objects update errors: 0
#Objects reconciled (updated): 0 (0 warnings)
#Objects reconciled (unchanged): 0 (0 warnings)
#Objects reconciliation errors: 0
#Replica disappeared, no action taken: 0

同步输出表明只有 1 个对象已更新。这也可以在同步数据源的"状态"选项卡上查看：

然后导航到人员 “Claude Monet” 的详细信息：

第三次同步：创建新联系人

接下来，在 iTop 根目录下 data 目录中的文本文件 “persons.csv” 末尾添加一行：

primary_key;name;first_name;org_id;email;status;function;phone;notify
1;Monet;Claude;Demo;claude.monet@demo.com;Active;Famous painter;+33123456789;Yes
2;Flaubert;Gustave;IT Department;gustave.flaubert@demo.com;Active;;+33987654321;No
3;Mondrian;Piet;Demo;p.m@demo.com;Active;;+334433221100;No

使用相同的命令再次启动导入和同步：

php synchro/synchro_import.php --auth_user=admin --auth_pwd=admin --csvfile=./data/persons.csv --data_source_id=1 --output=summary

输出如下：

#Load--------------
#------------------
#Data Source: 1
#Synchronize: 1
#Class: Person
#Separator: ;
#Qualifier: "
#Charset Encoding:UTF-8
#Date format: <none>
#Data Size: 294
#Data Lines: 3
#Columns: primary_key, name, first_name, org_id, email, status, function, phone, notify
#Output format: summary
#Simulate: 0
#Change tracking comment:
#Issues (before synchro): 0
#Created (before synchro): 1
#Updated (before synchro): 2
#Synchronization---
#------------------
#Replicas: 3
#Replicas touched since last synchro: 3
#Objects deleted: 0
#Objects deletion errors: 0
#Objects obsoleted: 0
#Objects obsolescence errors: 0
#Objects created: 1 (0 warnings)
#Objects creation errors: 0
#Objects updated: 0 (0 warnings)
#Objects update errors: 0
#Objects reconciled (updated): 0 (0 warnings)
#Objects reconciled (unchanged): 0 (0 warnings)
#Objects reconciliation errors: 0
#Replica disappeared, no action taken: 0

同步输出表明只有 1 个对象已更新。这也可以在同步数据源的"状态"选项卡上查看：

使用页面左上角的全局搜索搜索 “Contact:Piet”，然后点击对象名称以显示其详细信息。

第四次同步：错误案例

然后在 iTop 根目录下 “data” 目录中的文本文件 “persons.csv” 末尾再添加一行：

primary_key;name;first_name;org_id;email;status;function;phone;notify
1;Monet;Claude;Demo;claude.monet@demo.com;Active;Famous painter;+33123456789;Yes
2;Flaubert;Gustave;IT Department;gustave.flaubert@demo.com;Active;;+33987654321;No
3;Mondrian;Piet;Demo;p.m@demo.com;Active;;+334433221100;No
4;Klimt;Gurstav;Test;gustav.klimt@demo.com;Active;;+335566778899;No

使用相同的命令再次启动导入和同步：

php synchro/synchro_import.php --auth_user=admin --auth_pwd=admin --csvfile=./data/persons.csv --data_source_id=1 --output=summary

输出如下：

#Load--------------
#------------------
#Data Source: 5
#Synchronize: 1
#Class: Person
#Separator: ;
#Qualifier: "
#Charset Encoding:UTF-8
#Date format: <none>
#Data Size: 361
#Data Lines: 4
#Columns: primary_key, name, first_name, org_id, email, status, function, phone, notify
#Output format: summary
#Simulate: 0
#Change tracking comment:
#Issues (before synchro): 0
#Created (before synchro): 1
#Updated (before synchro): 3
#Synchronization---
#------------------
#Replicas: 4
#Replicas touched since last synchro: 4
#Objects deleted: 0
#Objects deletion errors: 0
#Objects obsoleted: 0
#Objects obsolescence errors: 0
#Objects created: 0 (0 warnings)
#Objects creation errors: 1
#Objects updated: 0 (0 warnings)
#Objects update errors: 0
#Objects reconciled (updated): 0 (0 warnings)
#Objects reconciled (unchanged): 0 (0 warnings)
#Objects reconciliation errors: 0
#Replica disappeared, no action taken: 0

同步输出表明有一个错误。

您可以点击 ‘Show’ 以获取有关刚刚发生的错误的更多详细信息。

然后修改 iTop 根目录下 “data” 目录中的文本文件 “persons.csv”，修复最后一行（将 Test 替换为 Demo）：

primary_key;name;first_name;org_id;email;status;function;phone;notify
1;Monet;Claude;Demo;claude.monet@demo.com;Active;Famous painter;+33123456789;Yes
2;Flaubert;Gustave;IT Department;gustave.flaubert@demo.com;Active;;+33987654321;No
3;Mondrian;Piet;Demo;p.m@demo.com;Active;;+334433221100;No
4;Klimt;Gurstav;Demo;gustav.klimt@demo.com;Active;;+335566778899;No

使用相同的命令再次启动导入和同步：

php synchro/synchro_import.php --auth_user=admin --auth_pwd=admin --csvfile=./data/persons.csv --data_source_id=1 --output=summary

应该没有错误，并且联系人 Gustav Klimt 在 Demo 组织中创建。

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

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

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

Docs: REST/JSON API 测试台

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

本文档介绍 iTop REST/JSON API 测试台。更多详细内容请参考 iTop 官方文档。

概述

iTop 提供了一个在线 REST/JSON API 测试台，你可以通过表单连接到自己的 iTop 服务器，测试 API 的 list_operations 和 core/get 等操作。

你可以在 jsfiddle 中查看对应的代码并进行调整。

使用方式

在测试台页面中填写以下信息：

iTop 服务器 URL：你的 iTop 服务器地址（末尾不带斜杠 /）
iTop 登录名：你的 iTop 账号
密码：你的 iTop 密码
API 版本：选择要使用的 API 版本
操作：选择要测试的操作（如 List Operations）
格式：选择 JSON 或 JSON-P

填写完成后，点击执行即可查看返回结果。

示例结果

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

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

Docs: 导出数据 - export.php

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

本文档介绍 iTop 的通用数据导出 Web 服务 export.php。该服务基于 OQL 查询导出数据，支持多种输出格式，可通过命令行或 HTTP 请求调用。更多详细内容请参考 iTop 官方文档。

用途

iTop 提供了一个通用的 Web 服务，用于基于 OQL 查询导出任何数据。这可用于从 iTop 提取数据，以便在第三方工具中使用。此 Web 服务可以返回多种格式的数据：

HTML
CSV
XML
Spreadsheet（纯 HTML，用于导入 Excel 或 OpenOffice）
XLSX（Excel 2007、2010、2013…）

此服务可以通过命令行接口在 iTop 服务器本地调用，也可以通过 HTTP 请求远程调用。

使用方法

命令行接口

php /var/www/itop/webservices/export.php --auth_login=login --auth_pwd=password --expression=query --format=csv --fields=<以逗号分隔的字段列表>

远程 Web 访问

有多种方式可以通过 Web 连接远程访问该服务。以下是使用 wget 命令的语法：

wget --http-user=login --http-password=password http://itopserver/webservices/export.php?expression=query&format=csv&fields=<以逗号分隔的字段列表>

参数

参数	描述	默认值
param_file	参数文件 - 参见参数文件	-
auth_login	用户登录名 - 仅 CLI 模式	-
auth_pwd	用户密码 - 仅 CLI 模式	-
expression	OQL 查询	如果缺少 ‘query’ 则为必填
query	存储在查询手册中的查询标识符。参见查询手册	如果缺少 ’expression’ 则为必填
format	`spreadsheet`（推荐用于与 MS-Excel Web 查询集成）、`html`、`xml`、`csv` 或 `xlsx`	html
fields	以逗号分隔的属性列表（例如 “name,brand,model”）；对 XML 输出无效；对 1.2（RC）之前的 HTML 版本无效	由 `<expression>` 指定的类的所有属性代码。这些属性未本地化
no_localize	如果设置为 0，则标题和值将使用已登录用户的语言进行本地化。设置为 1 以使用内部属性代码和值（枚举）	0

输出

HTML

Spreadsheet

此格式专用于集成到电子表格中。特别是，这是与 Excel Web 查询一起使用的推荐方法。

有关更多信息，请参阅文章 “如何使用 iTop 查询创建 Excel 报告”。

XML

<?xml version="1.0" encoding="UTF-8"?>
<Set>
 <Server alias="Server" id="1">
 <name>dbserver1.demo.com</name>
 <status>production</status>
 <org_id>2</org_id>
 <importance>medium</importance>
 <contact_list>Sorry, no yet implemented</contact_list>
 <document_list>Sorry, no yet implemented</document_list>
 <solution_list>Sorry, no yet implemented</solution_list>
 <contract_list>Sorry, no yet implemented</contract_list>
 <ticket_list>Sorry, no yet implemented</ticket_list>
 <brand>HP</brand>
 <model>DL380</model>
 <serial_number></serial_number>
 <asset_ref></asset_ref>
 <nwinterface_list>Sorry, no yet implemented</nwinterface_list>
 <description></description>
 <location_id>1</location_id>
 <location_details></location_details>
 <management_ip>10.1.1.10</management_ip>
 <default_gateway>255.255.255.0</default_gateway>
 <cpu>2</cpu>
 <ram>16Gb</ram>
 <hdd>120Gb</hdd>
 <os_family>Linux</os_family>
 <os_version>Debian (Lenny)</os_version>
 <application_list>Sorry, no yet implemented</application_list>
 <patch_list>Sorry, no yet implemented</patch_list>
 </Server>
 <Server alias="Server" id="6">
 <name>webserver.demo.com</name>
 <status>production</status>
 <org_id>2</org_id>
 <importance>medium</importance>
 <contact_list>Sorry, no yet implemented</contact_list>
 <document_list>Sorry, no yet implemented</document_list>
 <solution_list>Sorry, no yet implemented</solution_list>
 <contract_list>Sorry, no yet implemented</contract_list>
 <ticket_list>Sorry, no yet implemented</ticket_list>
 <brand>IBM</brand>
 <model>x3400 Tower Server</model>
 <serial_number></serial_number>
 <asset_ref></asset_ref>
 <nwinterface_list>Sorry, no yet implemented</nwinterface_list>
 <description></description>
 <location_id>1</location_id>
 <location_details></location_details>
 <management_ip>10.1.1.20</management_ip>
 <default_gateway>255.255.255.0</default_gateway>
 <cpu>4</cpu>
 <ram>8Gb</ram>
 <hdd>240Gb</hdd>
 <os_family>Unix</os_family>
 <os_version>AIX 4.0</os_version>
 <application_list>Sorry, no yet implemented</application_list>
 <patch_list>Sorry, no yet implemented</patch_list>
 </Server>
</Set>

CSV

id,Name,Management IP
1,"dbserver1.demo.com","10.1.1.10"
6,"webserver.demo.com","10.1.1.20"

允许的用户

此页面的使用没有任何限制。

历史版本

0.9 首次实现此功能
1.2.1 添加参数 ‘query’，作为 ’expression’ 的替代方案
1.2.1 添加格式 ‘spreadsheet’，可拆分日期和时间列
1.2.1 修复 HTTPS 和 MS-IIS 的停止问题（Trac:#485）
1.2.1 参数文件可以指定为参数（文档有误：实际上未实现）
1.2.1 分支 Spreadsheet 格式：修复时间问题（Trac:#541）。解决方法是使用 XML 格式（Excel 支持此格式）
2.0：添加标志 no_localize
2.1.0：添加 XLSX 格式

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

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

Docs: 通过 API 创建工单

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

本指南演示如何通过 REST/JSON API 自动创建 iTop 工单，适用于监控告警自动转工单、邮件转工单等场景。

概述

本页包含各种语言的示例脚本，用于从命令行在 iTop 中创建工单。这些脚本使用 iTop 的 REST/JSON API 在远程 iTop 服务器上创建工单（脚本必须通过 http/https 访问 iTop）。这些脚本旨在与 Nagios 一起使用，因为它们需要 4 个参数：host、service、service_status 和 service_state_type，但唯一有意义的参数是 host，并且调整脚本以满足您的特定需求非常容易。

选择您最喜欢的脚本语言，不要犹豫定制它。

使用 PHP

本节提供了一个用 PHP 脚本语言编写的示例脚本，用于在（远程）iTop 中使用 REST/JSON Web 服务创建工单。为了简化此示例，仅执行了最少的参数验证和返回状态验证。

要求：带有 cURL 模块的 PHP。

限制：Nagios 中的 “host” 值必须对应于 iTop 中唯一的 FunctionalCI。

以下 PHP 脚本创建一个 UserRequest 工单（您可以将配置更改为创建 Incident 或 Change），并将提供的 host（= FunctionalCI）附加到它。工单在与 host 相同的组织中创建。

#!/usr/bin/php
<?php
// Configuration
$ITOP_URL = 'https://demo.combodo.com/simple';
$ITOP_USER = 'admin';
$ITOP_PWD = 'admin';
$TICKET_CLASS = 'UserRequest';
$TITLE = 'Service Down on %1$s';
$DESCRIPTION = 'The Service "%2$s" is down on "%1$s"';
$COMMENT = 'Created from PHP';

if ($argc != 5)
{
 echo "Usage: {$argv[0]} <host> <service> <service_status> <service_state_type>\n";
 exit;
}
$host = $argv[1];
$service = $argv[2];
$service_status = $argv[3];
$service_state_type = $argv[4];
$url = $ITOP_URL.'/webservices/rest.php?version=1.0';

if (($service_status != "OK") && ($service_status != "UP") && ($service_state_type == "HARD"))
{
 $payload = array(
 'operation' => 'core/create',
 'class' => $TICKET_CLASS,
 'fields' => array(
 'org_id' => sprintf('SELECT Organization AS O JOIN FunctionalCI AS CI ON CI.org_id = O.id WHERE CI.name="%1$s"', $host),
 'title' => sprintf($TITLE, $host, $service),
 'description' => sprintf($DESCRIPTION, $host, $service),
 'functionalcis_list' => array(
 array('functionalci_id' => sprintf("SELECT FunctionalCI WHERE name='%s'", $host), 'impact_code' => 'manual'),
 ),
 ),
 'comment' => $COMMENT,
 'output_fields' => 'id',
 );

 $data = array(
 'auth_user' => $ITOP_USER,
 'auth_pwd' => $ITOP_PWD,
 'json_data' => json_encode($payload)
 );

 $options = array(
 CURLOPT_POST => count($data),
 CURLOPT_POSTFIELDS => http_build_query($data),
 // Various options...
 CURLOPT_RETURNTRANSFER => true, // return the content of the request
 CURLOPT_HEADER => false, // don't return the headers in the output
 CURLOPT_FOLLOWLOCATION => true, // follow redirects
 CURLOPT_ENCODING => "", // handle all encodings
 CURLOPT_AUTOREFERER => true, // set referer on redirect
 CURLOPT_CONNECTTIMEOUT => 120, // timeout on connect
 CURLOPT_TIMEOUT => 120, // timeout on response
 // Disabling SSL verification
 CURLOPT_SSL_VERIFYPEER => false, // Disable SSL certificate validation
 CURLOPT_SSL_VERIFYHOST => false, // Disable host vs certificate validation
 );

 $handle = curl_init($url);
 curl_setopt_array($handle, $options);
 $response = curl_exec($handle);
 $errno = curl_errno($handle);
 $error_message = curl_error($handle);
 curl_close($handle);

 if ($errno !== 0)
 {
 echo "Problem opening URL: $url, $error_message\n";
 exit;
 }
 $decoded_response = json_decode($response, true);
 if ($decoded_response === false)
 {
 echo "Error: ".print_r($response, true)."\n";
 }
 else if ($decoded_response['code'] != 0)
 {
 echo $decoded_response['message']."\n";
 }
 else
 {
 echo "Ticket created.\n";
 }
}
else
{
 echo "Service state type !='HARD', doing nothing.\n";
}

用法

create-ticket.php <host> <service> <service_status> <service_state_type>

配置

编辑脚本开头的以下行（在脚本开头）以根据您的环境进行调整：

// Configuration
$ITOP_URL = 'https://demo.combodo.com/simple';
$ITOP_USER = 'admin';
$ITOP_PWD = 'admin';
$TICKET_CLASS = 'UserRequest';
$TITLE = 'Service Down on %1$s';
$DESCRIPTION = 'The Service "%2$s" is down on "%1$s"';
$COMMENT = 'Created from PHP'

故障排除

您可以通过手动运行脚本来测试工单创建。例如，如果您的 iTop 中存在名为 Server1 的服务器，您可以运行以下命令来创建工单：

create-ticket.php "Server1" "Manual Test" "DOWN" "HARD"

使用 Perl

本节提供了一个用 Perl 脚本语言编写的示例脚本，用于在（远程）iTop 中使用 REST/JSON Web 服务创建工单。为了简化此示例，仅执行了最少的参数验证和返回状态验证。

要求：带有 LWP 和 JSON 模块的 Perl。

限制：Nagios 中的 “host” 值必须对应于 iTop 中唯一的 FunctionalCI。

以下 Perl 脚本创建一个 UserRequest 工单（您可以将配置更改为创建 Incident 或 Change），并将提供的 host（= FunctionalCI）附加到它。工单在与 host 相同的组织中创建。

#!/usr/bin/perl
use strict;
use warnings;
use LWP 5.64;
use JSON;

# Default values
my $ITOP_URL = 'https://demo.combodo.com/simple';
my $ITOP_LOGIN = "admin";
my $ITOP_PWD = "admin";
my $TICKET_CLASS = 'UserRequest';
my $DEFAULT_DESCRIPTION = 'Service "%1$s" is down on host "%2$s"';
my $DEFAULT_TITLE = 'Service down on "%1$s"';
my $COMMENT = "Created from $0";

# Parameters checking
my ($host, $service, $service_status, $service_state_type) = @ARGV;
if (not defined $host)
{
 die "Parameter 1: 'host' needed.\n";
}
if (not defined $service)
{
 die "Parameter 2: 'service' needed.\n";
}
if (not defined $service_status)
{
 die "Parameter 3: 'service status' needed.\n";
}
if (not defined $service_state_type)
{
 die "Parameter 4: 'service state type' needed.\n";
}

if ( ($service_status ne "OK" ) && ( $service_status ne "UP" ) && ( $service_state_type eq "HARD" ))
{
 my $url = "$ITOP_URL/webservices/rest.php?version=1.0";
 my $browser = LWP::UserAgent->new;
 $browser->ssl_opts(verify_hostname => 0, SSL_verify_mode => 0x00);

 my %ci_link = ( 'functionalci_id' => "SELECT FunctionalCI WHERE name='$host'", 'impact_code' => 'manual');

 my %fields = (
 'org_id' => "SELECT Organization AS O JOIN FunctionalCI AS CI ON CI.org_id=O.id WHERE CI.name='$host'",
 'title' => sprintf($DEFAULT_TITLE, $host),
 'description' => sprintf($DEFAULT_DESCRIPTION, $service, $host),
 'functionalcis_list' => [ \%ci_link ],
 );
 my %data = (
 'operation' => 'core/create',
 'class' => $TICKET_CLASS,
 'comment' => $COMMENT,
 'output_fields' => 'id',
 'fields' => \%fields,
 );

 my $response = $browser->post($url, [
 'auth_user' => $ITOP_LOGIN,
 'auth_pwd' => $ITOP_PWD,
 'json_data' => encode_json \%data,
 ]);

 if ($response->is_success)
 {
 my $output = decode_json( $response->decoded_content); # or whatever
 if ($output->{'code'} != 0)
 {
 print $output->{'message'}."\n";
 }
 else
 {
 print "Ticket created.\n";
 }
 }
 else
 {
 die $response->status_line;
 }
}
else
{
 print "Service state type !='HARD', doing nothing.\n";
}

用法

create-ticket.pl <host> <service> <service_status> <service_state_type>

配置

编辑脚本开头的以下行（在脚本开头）以根据您的环境进行调整：

# Default values
my $ITOP_URL = 'https://demo.combodo.com/simple';
my $ITOP_LOGIN = "admin";
my $ITOP_PWD = "admin";
my $TICKET_CLASS = 'UserRequest';
my $DEFAULT_DESCRIPTION = 'Service "%1$s" is down on host "%2$s"';
my $DEFAULT_TITLE = 'Service down on "%1$s"';
my $COMMENT = "Created from $0";

故障排除

您可以通过手动运行脚本来测试工单创建。例如，如果您的 iTop 中存在名为 Server1 的服务器，您可以运行以下命令来创建工单：

create-ticket.pl "Server1" "Manual Test" "DOWN" "HARD"

使用 Python

本节提供了一个用 python 脚本语言编写的示例脚本，用于在（远程）iTop 中使用 REST/JSON Web 服务创建工单。为了简化此示例，仅执行了最少的参数验证和返回状态验证。

要求：带有 requests、json 和（显然）sys 包的 python。

限制：Nagios 中的 “host” 值必须对应于 iTop 中唯一的 FunctionalCI。

以下 python 脚本创建一个 UserRequest 工单（您可以将配置更改为创建 Incident 或 Change），并将提供的 host（= FunctionalCI）附加到它。工单在与 host 相同的组织中创建。

#!/usr/bin/python
import requests
import json
import sys

ITOP_URL = 'https://demo.combodo.com/simple'
ITOP_USER = 'admin'
ITOP_PWD = 'admin'
TICKET_CLASS = 'UserRequest'
TITLE = 'Service down on %(host)s'
DESCRIPTION = 'The service %(service)s is down on %(host)s'
COMMENT = 'Created from Python'

if len(sys.argv) != 5:
 print "Usage: "+sys.argv[0]+" host service service_status service_state_type\n"
 sys.exit()
else:
 print str(sys.argv)
 host = sys.argv[1]
 service = sys.argv[2]
 service_status = sys.argv[3]
 service_state_type = sys.argv[4]

if (service_status != "OK") and (service_status != "UP") and (service_state_type == "HARD" ):
 json_data = {
 'operation': 'core/create',
 'class': TICKET_CLASS,
 'fields': {
 'title': TITLE % {'host': host },
 'description': DESCRIPTION % {'host': host, 'service': service },
 'org_id': 'SELECT Organization AS O JOIN FunctionalCI AS CI ON CI.org_id = O.id WHERE CI.name="%(host)s"' % {'host': host},
 'functionalcis_list': [ {
 'functionalci_id': "SELECT FunctionalCI WHERE name='%(host)s'" % {'host': host},
 'impact_code': 'manual',
 }],
 },
 'comment': COMMENT,
 'output_fields': 'id',
 }
 encoded_data = json.dumps(json_data)
 r = requests.post(ITOP_URL+'/webservices/rest.php?version=1.0', verify=False, data={'auth_user': ITOP_USER , 'auth_pwd': ITOP_PWD , 'json_data': encoded_data})
 result = json.loads(r.text);
 if result['code'] == 0:
 print "Ticket created.\n"
 else:
 print result['message']+"\n"
else:
 print "Service state type !='HARD', doing nothing.\n"

用法

create-ticket.py <host> <service> <service_status> <service_state_type>

配置

编辑脚本开头的以下行以根据您的环境进行调整：

ITOP_URL = 'https://demo.combodo.com/simple'
ITOP_USER = 'admin'
ITOP_PWD = 'admin'
TICKET_CLASS = 'UserRequest'
TITLE = 'Service down on %(host)s'
DESCRIPTION = 'The service %(service)s is down on %(host)s'
COMMENT = 'Created from Python'

故障排除

您可以通过手动运行脚本来测试工单创建。例如，如果您的 iTop 中存在名为 Server1 的服务器，您可以运行以下命令来创建工单：

create-ticket.py "Server1" "Manual Test" "DOWN" "HARD"

使用 bash 和 wget

本节提供了一个用 bash 脚本语言编写的示例脚本，用于在（远程）iTop 中使用 REST/JSON Web 服务创建工单。为了简化此示例，仅执行了最少的参数验证和返回状态验证。

要求：bash 和 wget。

限制：Nagios 中的 “host” 值必须对应于 iTop 中唯一的 FunctionalCI。

以下 bash 脚本创建一个 UserRequest 工单（您可以将配置更改为创建 Incident 或 Change），并将提供的 CI 附加到它。工单在与 CI 相同的组织中创建。

#!/bin/bash
##################################################################################
# #
# Example script for creating a UserRequest ticket via the REST/JSON webservices #
# #
##################################################################################

# iTop location and credentials, change them to suit your iTop installation
ITOP_URL="https://demo.combodo.com/simple"
ITOP_USER="admin"
ITOP_PWD="admin"


# Parameters checking, see below for default values
if [ "$1" == "" ]; then
 echo "Missing parameter 1: host"
 exit -1
else
 HOST="$1"
fi

if [ "$2" == "" ]; then
 echo "Missing parameter 2: Service"
 exit -1
else
 SERVICE="$2"
fi

if [ "$3" == "" ]; then
 echo "Missing parameter 3: Service Status"
 exit -1
else
 SERVICE_STATUS="$3"
fi

if [ "$4" == "" ]; then
 echo "Missing parameter 4: Service State Type"
 exit -1
else
 SERVICE_STATUS_TYPE="$4"
fi

# Default values, adapt them to your configuration
TICKET_CLASS="UserRequest"
ORGANIZATION="SELECT Organization JOIN FunctionalCI AS CI ON CI.org_id=Organization.id WHERE CI.name='"${HOST}"'"
TITLE="Service Down on $1"
DESCRIPTION="The service $SERVICE is in state $SERVICE_STATUS on $HOST"

# Let's create the ticket via the REST/JSON API
if [[ ( "$SERVICE_STATUS" != "OK" ) && ( "$SERVICE_STATUS" != "UP" ) && ( "$SERVICE_STATUS_TYPE" == "HARD" ) ]]; then
 CIS_LIST='[{"functionalci_id":"SELECT FunctionalCI WHERE name=\"'"$1"'\"", "impact_code": "manual"}]'
 JSON_DATA='{"operation":"core/create", "class":"'"${TICKET_CLASS}"'", "fields": {"functionalcis_list":'"${CIS_LIST}"', "org_id":"'"${ORGANIZATION}"'", "title":"'"$TITLE"'", "description":"'"$DESCRIPTION"'"}, "comment": "Created by the Monitoring", "output_fields": "id"}'

 RESULT=`wget -q --post-data='auth_user='"${ITOP_USER}"'&auth_pwd='"${ITOP_PWD}"'&json_data='"${JSON_DATA}" --no-check-certificate -O - "${ITOP_URL}/webservices/rest.php?version=1.0"`

 PATTERN='"key":"([0-9])+"'
 if [[ $RESULT =~ $PATTERN ]]; then
 echo "Ticket created successfully"
 else
 echo "ERROR: failed to create ticket"
 echo $RESULT
 fi
else
 echo "Service State Type != HARD, doing nothing"
fi

用法

create-ticket.bash <host> <service> <service_status> <service_state_type>

配置

更改脚本顶部的 3 行以适应您的环境：

ITOP_URL="https://demo.combodo.com/simple"
ITOP_USER="admin"
ITOP_PWD="admin"

然后更改默认值以满足您的需求：

# Default values, adapt them to your configuration
TICKET_CLASS="UserRequest"
ORGANIZATION="SELECT Organization JOIN FunctionalCI AS CI ON CI.org_id=Organization.id WHERE CI.name='"${HOST}"'"
TITLE="Service Down on $1"
DESCRIPTION="The service $SERVICE is in state $SERVICE_STATUS on $HOST"

故障排除

您可以通过手动运行脚本来测试工单创建。例如，如果您的 iTop 中存在名为 Server1 的服务器，您可以运行以下命令来创建工单：

create-ticket.bash "Server1" "Manual Test" "DOWN" "HARD"

使用 bash 和 curl

本节提供了一个用 bash 脚本语言编写的示例脚本，用于在（远程）iTop 中使用 REST/JSON Web 服务更新工单。

复制粘贴此命令作为示例：

curl -X POST -F 'version=1.3' -F 'auth_user=admin' -F 'auth_pwd=admin' http://localhost/itop/webservices/rest.php --form-string 'json_data={"operation":"core/create","comment":"Synchronization from blah...", "class":"UserRequest","output_fields":"id, friendlyname", "fields":{"org_id":"SELECT Organization WHERE id=3", "caller_id":{"name":"monet","first_name":"claude"},"title":"issue blah","description":"something happened"}}'

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

2024/09/10 10:25 by127.0.0.1

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