cqtssetup.pl

Realiza tareas de configuración para la búsqueda de texto completo.

Sinopsis

Genera un archivo de entidades que se pueden enviar:
cqperl cqtssetup.pl –d nombre_bd –s conjunto_bd –u usuario –p contraseña –o Entity
Genera un archivo de propiedades de búsqueda de ClearQuest:
cqperl cqtssetup.pl –d nombre_bd –s conjunto_bd –u usuario –p contraseña –o CQ[ -f archivo_entidad ]
Genera un archivo de esquema de búsqueda de Solr:
cqperl cqtssetup.pl –d nombre_bd –s conjunto_bd –u usuario –p contraseña –o Solr[ -f archivo_entidad ]

Descripción

El mandato cqtssetup.pl lleva a cabo tareas de configuración para la característica de búsqueda de texto completo, según la modalidad de operación que especifica la opción -o: Entity, CQ, o Solr. La salida es un archivo con un nombre relacionado con la modalidad de operación:
  • Entity-nombre_bd-nombre_conjuntobd.txt
  • CQ-nombre_bd-nombre_conjuntobd.xml
  • Solr-nombre_bd-nombre_conjuntobd.xml
Los pasos para utilizar cqtssetup.pl son los siguientes:
  1. Generar un archivo de todas las entidades que se pueden enviar (-o Entity). Estas entidades y sus campos son los candidatos para la búsqueda.
  2. Generar el archivo de propiedades de búsqueda de ClearQuest (-o CQ) que utilizarán el extractor de recursos (cqtsdbcrawler.pl) y la característica de búsqueda. Normalmente se especifica la salida editada de cqtssetup.pl ... -o Entity como argumento para la opción -f.
  3. Generar el archivo de esquema de búsqueda de Solr (-o Solr), que especifica cómo se indexan las entidades. Normalmente se especifica la salida de cqtssetup.pl ... -o CQ como argumento para la opción -f.

Este mandato está instalado en el directorio de instalación del producto predeterminado.

Opciones y argumentos

–d nombre_bd
Nombre de la bases de datos.
–s conjunto_bd
Nombre del conjunto de bases de datos.
–u usuario
Nombre del usuario.
–p contraseña
Contraseña.
–o { Entity | CQ | Solr }
La modalidad de operación:
  • Entity crea el archivo de entidades.
  • CQ crea el archivo de propiedades de búsqueda.
  • Solr crea el archivo de esquema de búsqueda de Solr.
–f archivo_entidades
El archivo de entidades. Esta opción únicamente puede especificarse con las opciones CQ y Solr. Cuando se omite esta opción, todos los tipos de entidad que se pueden enviar (y sus campos) que se encuentran en la base de datos se utilizan como argumento del mandato.

El archivo de entidades

El archivo de entidades se genera cuando se especifica -o Entity como modalidad de operación. Contiene las entidades que se pueden enviar encontradas en la base de datos. Dado que el desarrollador de esquemas de ClearQuest entiende bien estas entidades, no es necesario explicar adicionalmente el archivo de entidades.

Atención: Para que funcione la característica de búsqueda de texto completo se deben indexar como mínimo los tres campos siguientes:
  • record_type
  • dbid
  • version
La indexación de campos adicionales aumenta las ventajas de la característica de búsqueda de texto completo sin incrementar de forma significativa el tamaño del índice.

El archivo de propiedades de búsqueda de ClearQuest

El archivo de propiedades de búsqueda de ClearQuest se genera cuando se especifica -o CQ como modalidad de operación. Contiene diversas secciones: motor de búsqueda, rastreador de bases de datos, base de datos y entidad. Si se replica la base de datos, existen diversas instancias de cada sección. Cada instancia corresponde a una réplica y puede requerir una configuración que sea específica de la réplica.

La sección del motor de búsqueda

Esta sección describe las etiquetas XML de la sección del motor de búsqueda del archivo, CQ-nombrebd-nombreconjuntobd.xml. A continuación se proporciona un ejemplo de esta sección:
<!- 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>
Especifica la configuración que se utiliza para comunicarse con el motor de búsqueda. Para una base de datos no replicada, sitename="<local>".
Cuando se replica la base de datos, existe una instancia de esta etiqueta para cada réplica y el valor del nombre de sitio especifica el sitio de esta réplica. La característica de búsqueda de texto completo lee el valor del nombre de sitio. Si el valor no coincide con el nombre del sitio, la característica de búsqueda se inhabilita.
No es necesario modificar esta etiqueta.
<searchrequest>
Especifica el URL del servidor del motor de búsqueda y cómo comunicarse con este servidor. No es necesario modificar esta etiqueta.
<searchprop>
Especifica la página predeterminada y los tamaños de memoria caché.
  • pagesize especifica el número de coincidencias que deben devolverse por página.
  • cachesize especifica el número de coincidencias para leer y guardar en la memoria caché.
No es necesario modificar esta etiqueta.

La sección del rastreador de bases de datos

Esta sección describe las etiquetas XML de la sección del rastreador de bases de datos del archivo, CQnombre_bd-nombreconjuntobd.xml. A continuación se proporciona un ejemplo de esta sección:

<!- 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>
El extractor de registros lee el valor de esta etiqueta en las modalidades de ejecución de proceso por lotes y de actualización. Especifica la configuración del sitio que se utiliza para comunicarse con el motor de búsqueda. Para una base de datos no replicada, sitename="<local>".

Para una base de datos replicada, existe una etiqueta <CQDbCrawler> independiente para cada réplica, y cada instancia de sitename especifica el sitio de una réplica. En el caso de una base de datos replicada, el extractor de registros busca un valor de opción sitename que coincida con el nombre del sitio en el cual se ejecuta. Si no se encuentra ninguno, el extractor de registros no puede iniciarse.

<batch>, <update>
El mandato cqtsdbcrawler lee los valores de estas etiquetas en las modalidades de proceso por lotes y de actualización. Posiblemente querrá modificar sus valores para que adapten a su entorno de ClearQuest.
  • size especifica el número de registros que deben leerse a la vez antes de que se envíen al motor de búsqueda para su indexación.
  • delay especifica el tiempo, en segundos, que el extractor de registros espera entre el procesamiento de grupos de registros del tamaño especificado por size. El valor de delay predeterminado es de 600 segundos.
  • login_iteration especifica cuándo se crea un nuevo inicio de sesión. De forma predeterminada, un nuevo inicio de sesión se crea cada vez que se produce un delay. A continuación se expresan algunos valores válidos:
    -1
    Inicie la sesión una vez y permanezca conectado durante la ejecución de la aplicación.
    0 | 1
    Comportamiento predeterminado. La utilización de cada valor tiene el mismo efecto: inicie la sesión y cierre la sesión cada vez que el proceso se active en función del valor de delay.
    n
    Cierre la sesión e inicie la sesión la n vez que se active el proceso, en función del valor de delay.
  • url especifica cómo comunicarse con el motor de búsqueda para agregar registros al índice.
  • thread se aplica únicamente a la modalidad de proceso por lotes. Especifica el número de hebras para crear al ejecutar las consultas. Cuanto mayor es el número de hebras, más rápidamente se ejecuta la extraccion de registros. El número máximo de hebras permitidas es de 10. Los valores mayores de 10 se truncan en 10.
  • Actualice las referencias a localhost, del modo que corresponda:
    • Si el servicio de búsqueda de ClearQuest, Solr, se ejecuta en el mismo host que el servidor CM, localhost resulta suficiente.
    • Si dispone de un entorno distribuido o con equilibrio de carga con diversos servidores CM y un host de servicio de búsqueda de ClearQuest, o de bases de datos de varios usuarios indexados con perfiles de búsqueda de ClearQuest que residen en hosts distintos, o una configuración de ClearQuest MultiSite en la cual se utiliza un servicio de búsqueda común de ClearQuest para manejar solicitudes de servidores de CM a varias ubicaciones de ClearQuest MultiSite, especifique la dirección IP o el nombre de host (especificado como URL) para el host de búsqueda aplicable de ClearQuest en lugar de localhost.

Ejemplo

Si el valor de login_iteration es 10 y se cambia delay del valor predeterminado de 600 segundos a 60 segundos, se crea un inicio de sesión nuevo cada 10 minutos, mientras se produce una comprobación de registros nuevos o modificados de ClearQuest cada minuto. Esta acción permite que el índice de búsqueda de texto completo se sincronice con mayor proximidad con la base de datos de ClearQuest.

La sección de la base de datos

Esta sección describe las etiquetas XML de la sección de la base de datos del archivo, CQnombre_bd-nombreconjuntobd.xml. A continuación se proporciona un ejemplo de esta sección:

<!-- 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>
El extractor de registros lee el valor de esta etiqueta, en la modalidad de ejecución de proceso por lotes y de actualización; para conocer la configuración del sitio que debe utilizarse para comunicarse con la base de datos de ClearQuest y el servidor de gestión de cambios (CM) para extraer registros y supervisar actualizaciones a la base de datos. Cuando no se replica la base de datos, sitename="<local>".

Para una base de datos replicada, existe una instancia de CQDatabase para cada réplica, y sitename especifica el sitio de la réplica. El extractor de registros busca un sitename que coincida con el nombre del sitio en el cual se ejecuta; si no se encuentra ninguno, el extractor de registros no puede iniciarse.

No es necesario modificar esta etiqueta.

<cmserver>
Especifica el URL del servidor de gestión de cambios (CM). Modifique el valor de esta etiqueta según corresponda:
  • Si el servicio de búsqueda de ClearQuest, Solr, se ejecuta en el mismo host que el servidor CM, localhost resulta suficiente.
  • Si dispone de un entorno distribuido o con equilibrio de carga con diversos servidores CM y un host de servicio de búsqueda de ClearQuest, o de bases de datos de varios usuarios indexados con perfiles de búsqueda de ClearQuest que residen en hosts distintos, o una configuración de ClearQuest MultiSite en la cual se utiliza un servicio de búsqueda común de ClearQuest para manejar solicitudes de servidores de CM a varias ubicaciones de ClearQuest MultiSite, especifique la dirección IP o el nombre de host (especificado como URL) para el host de búsqueda aplicable de ClearQuest en lugar de localhost.
<repository>
Especifica el perfil de conexión de la base de datos. Modifique los valores siguientes en función de su perfil:
  • dbset especifica el nombre del conjunto de bases de datos.
  • dbname especifica el nombre de la base de datos.
  • username especifica la identidad que el extractor de registros asume para iniciar la sesión en ClearQuest.
  • password especifica la contraseña cifrada que genera cqtsdbcrawler.pl.
  • keyfile especifica el nombre completo de la vía de acceso que se utiliza para descifrar la contraseña.
Atención: Debe especificar un valor válido para username, password, y keyfile:
  • En un entorno de producción, utilice un archivo de claves y una contraseña cifrada.
  • Únicamente para prototipos y para pruebas puede elegir dejar el elemento de la contraseña en blanco y no utilizar un archivo de claves. No obstante, este escenario no debería utilizarse en un entorno de producción.

En caso contrario, se producirán errores a la hora de ejecutar el extractor de registros, cqdbtscrawler.pl, en modalidad de proceso por lotes o de actualización.

La sección de entidades

Esta sección describe las etiquetas XML de la sección de entidades del archivo, CQ-nombrebd-nombreconjuntobd.xml. A continuación se proporciona un ejemplo de esta sección:

<!- 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>
El valor de esta etiqueta lo lee el extractor de registros y la característica de búsqueda. Cuando se replica la base de datos de ClearQuest, las instancias de CQEntity deben ser coherentes entre todos los sitios, y la indexación (y por lo tanto los resultados de la búsqueda) no serán coherentes entre las réplicas.
<field>
El extractor de registros utiliza los valores de esta etiqueta para determinar si un campo está indexado y se puede buscar, del modo siguiente:
  • name especifica el nombre del campo.
  • index especifica si el campo está indexado o no. Cuando index="<true>", la entidad especificada está indexada y se puede buscar.
  • disp_order indica si el campo se visualiza en los resultados de la búsqueda, del modo siguiente:
    • El valor 0 significa que el campo no se visualiza.
    • El valor 1 significa que el campo se visualiza. Únicamente puede visualizarse un campo en una entidad.
    Atención: Todos los tipos de registro que se indexan utilizando la característica de búsqueda de texto completo deben tener únicamente un campo especificado con un valor disp_order de 1. Si existe más de un campo con un valor disp_order de 1, no se visualiza ningún resultado.

El archivo de esquema de búsqueda de Solr

El archivo de esquema de búsqueda de Solr se genera cuando se especifica -o Solr como modalidad de operación. Dado que se trata del caso de -o CQ, esta modalidad de operación toma como su entrada el archivo de entidad generado mediante la ejecución de este mandato en modalidad de entidad (-o Entity). No edite el archivo de esquema de búsqueda de Solr; como alternativa, copie secciones de este archivo en el archivo de esquema de Solr, schema.xml. (Para obtener información acerca de schema.xml, consulte la documentación de Solr).

La sección más importante del archivo de esquema de búsqueda de Solr es la sección del motor de búsqueda, que se muestra en el extracto siguiente:
<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>
Proporciona a Solr información acerca de la indexación de un campo:
  • name especifica el nombre de campo.
  • type especifica el tipo de datos.
  • indexed especifica si se debe indexar o no el campo.
  • stored especifica si los datos del campo deben almacenarse en el índice de Lucene.
  • required especifica si un documento debe contener el campo (y sus datos) para añadirlo al índice.
  • multivalued especifica si puede haber otra etiqueta <field> con este nombre de archivo.
No modifique esta etiqueta.
<unique_key>
Especifica el campo de la definición de documento de Lucene que debe utilizarse como identificador de documentos. Este campo lo leen Solr, Lucene, el extractor de registros y la característica de búsqueda de ClearQuest para identificar de forma exclusiva un registro de ClearQuest. No modifique esta etiqueta.
<defaultSearchfield>
Especifica el campo que debe utilizarse cuando se ejecuta una búsqueda sin un calificador de campo. Solr y Lucene utilizan este campo para buscar todos los campos de un registro. No modifique esta etiqueta.
<copyField>
Especifica que el contenido de un campo debe copiarse a otro campo, en este caso <defaultSearchfield>. No modifique esta etiqueta.

Ejemplos

  1. Genere un archivo de todas las entidades que se pueden enviar en la base de datos:
    cqperl cqtssetup.pl -d SAMPL -s TextSearch -u admin -p "" -o Entity

    Este mandato genera el archivo Entity-SAMPL-TextSearch.txt. El contenido del archivo es similar al del texto siguiente:

    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,…,…,…

    Edite el archivo para especificar los tipos de registro y los campos que se pueden buscar. Por ejemplo, si únicamente pueden buscarse registros del tipo Defect, suprima todas las líneas del archivo excepto la que empieza por Defect=. Si únicamente pueden buscarse algunos de los campos definidos por este tipo de registro, conserve únicamente estos campos y suprima el resto. Por ejemplo, si únicamente pueden buscarse Headline, Description y Severity, el archivo editado sería

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

    Tenga en cuenta que los campos record_type, dbid y version se conservan. La implementación de la búsqueda de texto completo tiene como requisito la indexación de estos tres campos.

  2. Genere un archivo de propiedades de búsqueda, especificando todo el archivo, Entity-SAMPL-TextSearch.txt, que generó el mandato anterior.
    cqperl cqtssetup.pl -d SAMPL -s TextSearch -u admin -p ""
    -o CQ -f Entity_SAMPLE_TextSearch.txt

    Este mandato genera el archivo, CQ-SAMPL-TextSearch.xml, que utilizan el extractor de registros (cqtsdbcrawler.pl) y la característica de búsqueda.

  3. Genere un archivo de esquema de búsqueda de Solr, especificando el archivo de entidades, Entity-SAMPL-TextSearch.txt.
    cqperl cqtssetup.pl -d SAMPL -s TextSearch -u admin -p ""
    -o Solr Entity-SAMPL-TextSearch.txt

    Este mandato genera el archivo, Solr-SAMPL-TextSearch.xml. No edite este archivo: copie secciones de este archivo en el archivo de Solr, schema.xml.

  4. Actualice el archivo de esquema de Solr schema.xml sustituyendo determinadas secciones por las secciones correspondientes del archivo Solr-SAMPL-TextSearch.xml:
    1. Sustituya la sección <fields> de schema.xml por la sección <fields> de Solr-SAMPL-TextSearch.xml.
    2. Sustituya la sección <copyfield> de la misma forma.
    3. Sustituya la sección <uniqueKey> de la misma forma. Esta sección ya debería existir si empezó con un archivo schema.xml ya existente.
    4. Sustituya la sección <defaultSearchField> de la misma forma. Esta sección ya debería existir si empezó con un archivo schema.xml ya existente.
  5. Reinicie WAS para que los cambios realizados sean efectivos.
Nota: Cuando edite su propio schema.xml, cambie el valor de <field name= ... por el nombre del esquema de bases de datos. Si utiliza ClearQuest MultiSite, especifique también el nombre del sitio local; por ejemplo, <field name="Acme Defect Tracking at Madrid"... La página web de administración de Solr reflejará este cambio.

Consulte también

cqtsdbcrawler.pl, setmasterpropertyfromfile


Comentarios