cqtssetup.pl

执行用于启用全文搜索的设置任务。

摘要

生成包含可提交实体的文件:
cqperl cqtssetup.pl –d dbname –s dbset –u user –p password –o Entity
生成 ClearQuest 搜索属性文件:
cqperl cqtssetup.pl –d dbname –s dbset –u user –p password –o CQ [ -f entity_file ]
生成 Solr 搜索模式文件:
cqperl cqtssetup.pl –d dbname –s dbset –u user –p password –o Solr [ -f entity_file ]

描述

cqtssetup.pl 命令根据 -o 选项指定的运行方式执行用于启用全文搜索功能的设置任务:EntityCQSolr。输出文件依据运行方式进行命名。
  • Entity-db_name-dbset_name.txt
  • CQ-db_name-dbset_name.xml
  • Solr-db_name-dbset_name.xml
cqtssetup.pl 的使用步骤如下所示:
  1. 生成包含所有可提交实体的文件(-o Entity)。 这些实体及其字段都可作为搜索对象。
  2. 生成 ClearQuest 搜索属性文件(-o CQ),以供记录抽取器(cqtsdbcrawler.pl)和搜索功能使用。通常,将 cqtssetup.pl ... -o Entity 的已编辑输出指定为 -f 选项的参数。
  3. 生成 Solr 搜索模式文件(-o Solr),该文件指定如何对实体建立索引。通常,将 cqtssetup.pl ... -o CQ 的输出指定为 -f 选项的自变量。

该命令安装在缺省产品安装目录中。

选项和自变量

–d dbname
数据库的名称。
–s dbset
数据库集的名称。
–u user
用户名。
–p password
密码。
–o { Entity | CQ | Solr }
运行方式:
  • Entity 创建实体文件
  • CQ 创建搜索属性文件
  • Solr 创建 Solr 搜索模式文件
–f entity_file
实体文件。该选项只能与选项 CQSolr 一起指定。 如果省略该选项,那么在数据库中找到的所有可提交实体类型(及其字段)将用作命令自变量。

实体文件

在将 -o Entity 指定为运行方式时,将生成实体文件。 该文件包含在数据库中找到的可提交实体。由于 ClearQuest 模式的开发者都十分熟悉这些实体,因此无需进一步说明该实体文件。

ClearQuest 搜索属性文件

在将 -o CQ 指定为运行方式时,将生成 ClearQuest 搜索属性文件。该文件包含以下几个部分:搜索引擎、数据库搜寻器、数据库和实体。如果复制了 ClearQuest 数据库,那么每个部分会有多个实例。每个实例对应一个副本,并且可能需要特定于该副本的配置。

搜索引擎部分

该部分描述了文件 CQ-db_name-dbset_name.xml 的搜索引擎部分中的 XML 标记。 下面是该部分的示例:
<!- Solr Search Engine default parameters -–>
<SearchEngine sitename="<local>" provider="Solr" version="1.2">
     <searchrequest retries="3"
          url=http://localhost:14080/solr/select/?q=%s&start=%d&rows=%d />
     <searchprop pagesize="25" cachesize="1000" />
</SearchEngine>
<SearchEngine>
指定与搜索引擎通信所用的配置。对于非复制数据库,sitename="<local>"
如果复制了数据库,那么每个副本都有一个该标记的实例,并且 sitename 的值用于指定该副本的站点。全文搜索功能将读取 sitename 的值。 如果该值与站点名称不匹配,那么将禁用搜索功能。
您无需修改该标记。
<searchrequest>
指定搜索引擎服务器 URL 以及与该服务器的通信方式。您无需修改该标记。
<searchprop>
指定缺省页面和高速缓存大小。
  • pagesize 指定每页可返回的命中数。
  • cachesize 指定可读取和高速缓存的命中数。
您无需修改该标记。

数据库搜寻器部分

该部分描述了文件 CQ-db_name-dbset_name.xml 的数据库搜寻器部分中的 XML 标记。 下面是该部分的示例:

<!- ClearQuest Database Crawler default parameters -->
<CQDbCrawler sitename="<local>">
     <batch size="250" delay="5" directory="./batch-output"
          url=http://localhost/solr/update/" />
     <update size="250" delay="300" login_iteration="1" directory="./update-output"
          url=http://localhost/solr/update/" />
</CQDbCrawler>
<CQDbcrawler>
记录抽取器在执行时以批处理方式和更新方式读取该标记的值。该标记指定与搜索引擎通信所用的站点配置。对于非复制数据库,sitename="<local>"

对于复制数据库,每个副本都有一个单独的 <CQDbCrawler> 标记,并且每个 sitename 实例都指定一个副本的站点。对于复制数据库,记录抽取器会查找与其所运行在的站点的名称相匹配的 sitename 值。如果未找到,那么记录抽取器将无法启动。

<batch>, <update>
cqtsdbcrawler 命令以批处理方式和更新方式读取这些标记的值。您可能希望根据您的 ClearQuest 环境修改这些标记的值。
  • size 指定在将记录发送给搜索引擎供其建立索引之前一次可读取的记录数。
  • delay 指定在处理两组记录(组大小由 size 指定)之间记录抽取器等待的时间(以秒为单位)。缺省 delay 值为 600 秒。
  • login_iteration 指定创建新登录会话的时间。缺省情况下,每次发生 delay 时都会创建一个新的登录会话。 有效值包括:
    -1
    登录一次,并且在应用程序运行时一直保持登录状态。
    0 | 1
    缺省行为。这两个值的效果相同:每次根据 delay 值唤醒进程时都会进行登录和注销。
    n
    在根据 delay 值第 n 次唤醒进程时登录和注销。
  • url 指定如何与搜索引擎进行通信以将记录添加到索引。
  • thread 仅适用于批处理方式。这指定执行查询时创建的线程数。线程越多,记录抽取速度越快。 允许的最大线程数为 10。大于 10 的值会被截取为 10。
  • 根据需要更新对 localhost 的任何引用:
    • 如果您的 ClearQuest 搜索服务 Solr 与 CM Server 运行在同一台主机上,那么 localhost 足够。
    • 如果您有一个负载均衡或分布式环境(包含多台 CM Server 和一台 ClearQuest 搜索服务主机);或者有多个用户数据库(利用位于不同主机上的 ClearQuest 搜索概要文件来建立索引);或者有一种 ClearQuest MultiSite 配置(使用公共 ClearQuest 搜索服务来处理来自各个 ClearQuest MultiSite 位置的 CM Server 请求);请指定适当 ClearQuest 搜索主机的 IP 地址或主机名(指定为 URL),来代替 localhost

示例

如果 login_iteration 的值为 10,并且您将 delay 的值从缺省值 600 秒更改为 60 秒,那么每 10 分钟会创建一个新的登录会话,同时每分钟都会检查是否出现新的或已修改的 ClearQuest 记录。这样全文搜索索引可以与 ClearQuest 数据库保持更紧密的同步。

数据库部分

该部分描述了文件 CQ-db_name-dbset_name.xml 的数据库部分中的 XML 标记。 下面是该部分的示例:

<!-- ClearQuest database and CM Server parameters -->
<CQDatabase sitename="<local>">
     <cmserver>http://localhost/TeamWeb/services/Team/</cmserver>
     <repository dbset="TextSearch" dbname="SAMPL"
          <username="admin" password="" keyfile=""></repository>
</CQDatabase>
<CQDatabase>
记录抽取器在执行时以批处理方式和更新方式读取该标记的值,以了解与 ClearQuest 数据库和 Change Managment(CM)Server 通信所用的站点配置,以便将记录和监视器更新抽取至数据库。 如果未复制数据库,那么 sitename="<local>"

对于复制数据库,每个副本都有一个 CQDatabase 实例,并利用 sitename 指定该副本的站点。记录抽取器会查找与其所运行在的站点名称相匹配的 sitename;如果未找到,那么记录抽取器将无法启动。

您无需修改该标记。

<cmserver>
指定 Change Management(CM)Server URL。根据需要修改该标记的值:
  • 如果您的 ClearQuest 搜索服务 Solr 与 CM Server 运行在同一台主机上,那么 localhost 足够。
  • 如果您有一个负载均衡或分布式环境(包含多台 CM Server 和一台 ClearQuest 搜索服务主机);或者有多个用户数据库(利用位于不同主机上的 ClearQuest 搜索概要文件来建立索引);或者有一种 ClearQuest MultiSite 配置(使用公共 ClearQuest 搜索服务来处理来自各个 ClearQuest MultiSite 位置的 CM Server 请求);请指定适当 ClearQuest 搜索主机的 IP 地址或主机名(指定为 URL),来代替 localhost
<repository>
指定数据库连接概要文件。根据您的概要文件修改以下值:
  • dbset 指定数据库集的名称。
  • dbname 指定数据库的名称。
  • username 指定记录抽取器登录 ClearQuest 所用的身份。
  • password 指定 cqtsdbcrawler.pl 生成的加密密码。
  • keyfile 指定用于解密密码的密钥文件的完整路径名。
注意: 必须为 usernamepasswordkeyfile 指定有效值:
  • 在生产环境中,请使用加密密码和密钥文件。
  • 只有在原型设计和测试阶段,才可以选择将密码元素留空且不使用密钥文件。但是在生产环境中不能使用此方案。

否则,以批处理方式或更新方式运行记录抽取器 cqdbtscrawler.pl 时就会发生错误。

实体部分

该部分描述了文件 CQ-db_name-dbset_name.xml 的实体部分中的 XML 标记。 下面是该部分的示例:

<!- ClearQuest entity parameters -->
<CQEntity name="Customer" index="true">
     <field name="schema_mastership" disp_order="0" index="true" />
     <field name="customer_name" disp_order="1" index="true" />
     <field name="phone" disp_order="0" index="true" />
     <field name="company_name" disp_order="0" index="true" />
          .
          .
          .
</CQEntity>
<CQEntity>
记录抽取器和搜索功能都将读取该标记的值。如果复制了 ClearQuest 数据库,那么 CQEntity 在所有站点上都必须保持一致,否则各副本之间的索引(及由此得到的搜索结果)将出现不一致。
<field>
记录抽取器使用该标记的值来确定字段是否建立索引并可搜索,如下所示:
  • name 指定字段的名称。
  • index 指定字段是否为索引。 index="<true>" 时,指定的实体将建立索引并可搜索。
  • disp_order 指示是否在搜索结果中显示字段,如下所示:
    • 值 0 表示不显示字段。
    • 值 1 表示将显示字段。一个实体中只有一个字段可显示。
    注意: 使用 ClearQuest 全文搜索功能建立索引的所有记录类型都只能有一个字段的 disp_order 值指定为 1。如果有多个字段的 disp_order 值指定为 1,那么将不显示任何结果。

Solr 搜索模式文件

在将 -o Solr 指定为运行方式时,将生成 Solr 搜索模式文件。与 -o CQ 一样,该运行方式接受以实体方式(-o Entity)运行该命令生成的实体文件作为其输入。 请勿编辑 Solr 搜索模式文件;但是可将该文件的各个部分复制到 Solr 模式文件 schema.xml。(有关 schema.xml 的信息,请参阅 Solr 文档。)

Solr 搜索模式文件的最重要部分是搜索引擎部分,其摘录如下所示:
<Solr>
	<fields>
		<field name="Operator_Value" type="text" indexed="true" stored="false" required="false" multivalued="true"></field>
		<field name="misc_info" type="text" indexed="true" stored="false" required="false" multivalued="true"></field>
...
		<field name="Resolution" type="text" indexed="true" stored="false" required="false" multivalued="false"></field>

...
		<field name="comments" type="text" indexed="true" stored="false" required="false" multivalued="true"></field>

...
		<field name="RATL_CQ_UNIQUE_FIELD" type="string" indexed="true" stored="true" required="true" multivalued="false"></field>
...
		<field name="RATL_CQ_ALL_FIELDS" type="text" indexed="true" stored="false" required="false" multivalued="true"></field>
	</fields>
</Solr>
<uniqueKey>RATL_CQ_UNIQUE_FIELD</uniqueKey>
<defaultSearchField>RATL_CQ_ALL_FIELDS</defaultSearchField>
<copyField source="Operator_Value" dest="RATL_CQ_ALL_FIELDS"></copyField>
<copyField source="misc_info" dest="RATL_CQ_ALL_FIELDS"></copyField>
...
<copyField source="Resolution" dest="RATL_CQ_ALL_FIELDS"></copyField>
...
<copyField source="Version" dest="RATL_CQ_ALL_FIELDS"></copyField>
...
<copyField source="comments" dest="RATL_CQ_ALL_FIELDS"></copyField>
...
<copyField source="Fax" dest="RATL_CQ_ALL_FIELDS"></copyField>
<field>
向 Solr 提供有关建立字段索引的信息:
  • name 指定字段名称。
  • type 指定数据类型。
  • indexed 指定是否对字段建立索引。
  • stored 指定是否将字段中的数据存储在 Lucene 索引中。
  • required 指定文档是否必须包含要添加至索引的字段(及其数据)。
  • multivalued 指定是否可存在另一个使用该字段名称的 <field> 标记。
请勿修改该标记。
<unique_key>
在 Lucene 文档定义中指定要用作文档标识的字段。Solr、Lucene、记录抽取器和 ClearQuest 搜索功能将读取该字段,来唯一识别 ClearQuest 记录。请勿修改该标记。
<defaultSearchfield>
指定在执行不含字段限定符的搜索时要使用的字段。Solr 和 Lucene 使用该字段来搜索某条记录中的所有字段。请勿修改该标记。
<copyField>
指定字段内容将复制到另一个字段,在本例中为 <defaultSearchfield>。请勿修改该标记。

示例

  1. 生成包含 SAMPL 数据库中所有可提交实体的文件:
    cqperl cqtssetup.pl -d SAMPL -s TextSearch -u admin -p "" -o Entity

    该命令会生成 Entity-SAMPL-TextSearch.txt 文件。该文件的内容类似于以下文本:

    Email_Rule=ratl_mastership,ratl_keysite,record_type,dbid,is_active,version,lock_version,locked_by,name,…,…,…
    Customer=ratl_mastership,ratl_keysite,dbid,is_active,version,lock_version,locked_by,record_type,Name,Phone,Fax,Email,CallTrackingID,…,…,…
    Project=ratl_mastership,ratl_keysite,dbid,is_active,version,lock_version,locked_by,…,…,…
    Defect=ratl_mastership,record_type,dbid,is_active,id,state,version,lock_version,locked_by,isduplicate,unduplicate_state,Headline,Description,Priority,Severity,Submitter,…,…,…

    编辑该文件以指定可搜索的记录类型和字段。例如,如果只可搜索类型为 Defect 的记录,请删除该文件中除以 Defect= 开头的行外的所有其他行。如果只可搜索由该记录类型定义的部分字段,请只保留这些字段,删除其他字段。例如,如果只可搜索“标题”、“描述”和“严重性”,那么编辑后的该文件如下所示

    Defect=record_type,dbid,version,Headline,Description,Severity

    注:将保留字段“记录类型”、“数据库标识”和“版本”。这样便可以实施对这三个字段建立索引的全文搜索。

  2. 生成搜索属性文件,在其中指定由上一条命令生成的实体文件 Entity-SAMPL-TextSearch.txt
    cqperl cqtssetup.pl -d SAMPL -s TextSearch -u admin -p ""
    -o CQ -f Entity_SAMPLE_TextSearch.txt

    该命令生成文件 CQ-SAMPL-TextSearch.xml,可供记录抽取器(cqtsdbcrawler.pl)和搜索功能使用。

  3. 生成 Solr 搜索模式文件,在其中指定实体文件 Entity-SAMPL-TextSearch.txt
    cqperl cqtssetup.pl -d SAMPL -s TextSearch -u admin -p ""
    -o Solr Entity-SAMPL-TextSearch.txt

    该命令生成文件 Solr-SAMPL-TextSearch.xml。请勿编辑该文件:可将该文件的各个部分复制到 Solr 文件 schema.xml。

  4. 通过将 Solr 模式文件 schema.xml 的某些部分替换为文件 Solr-SAMPL-TextSearch.xml 的相应部分,可以更新该模式文件:
    1. 将 schema.xml 的 <fields> 部分替换为 Solr-SAMPL-TextSearch.xml 的 <fields> 部分。
    2. 以相同方式替换 <copyfield> 部分。
    3. 以相同方式替换 <uniqueKey> 部分。如果使用的是现有的 schema.xml 文件,那么这一部分应该已存在。
    4. 以相同方式替换 <defaultSearchField> 部分。 如果使用的是现有的 schema.xml 文件,那么这一部分应该已存在。
  5. 重新启动 WAS,使所做的更改生效。
注: 在编辑您自己的 schema.xml 时,将 <field name= ... 的值更改为您的数据库模式的名称。如果使用 ClearQuest MultiSite,那么还要指定本地站点的名称;例如,<field name="Acme Defect Tracking at Madrid"... Solr 管理 Web 页面将反映此更改。

另请参阅

cqtsdbcrawler.plsetmasterpropertyfromfile


反馈