cqtssetup.pl

Réalise des tâches d'installation et de configuration pour la recherche en texte intégral.

Syntaxe

Générez un fichier d'entités pouvant être soumises pour les recherches :
cqperl cqtssetup.pl –d nombd –s ensemblebd –u utilisateur –p motdepasse –o entité
Générez un fichier de propriétés de recherche ClearQuest :
cqperl cqtssetup.pl –d nombd –s ensemblebd –u utilisateur –p motdepasse –o fichier_entité
Générez un fichier schéma de recherche Solr :
cqperl cqtssetup.pl –d nombd –s ensemblebd –u utilisateur –p motdepasse –o Solr [ -f fichier_entité ]

Description

La commande cqtssetup.pl réalise des tâches d'installation/configuration pour la fonction de recherche en texte intégral, en fonction du mode de fonctionnement spécifié par l'option -o : Entity, CQ ou Solr. La sortie de cette commande est un fichier nommé selon le mode de fonctionnement :
  • Entité-nom_bd-nom_ensemblebd.txt
  • CQ-nom_bd-nom_ensemblebd.xml
  • Solr-nom_bd-nom_ensemblebd.xml
L'utilisation de la commande cqtssetup.pl se décompose ainsi :
  1. Générez un fichier de toutes les entités (-o Entity) pouvant être soumises pour les recherches. Ces entités et leurs zones seront candidates aux recherches.
  2. Générez le fichier de propriétés de recherche ClearQuest (-o CQ) qui sera utilisé par l'extracteur d'enregistrements (cqtsdbcrawler.pl) et par la fonction de recherche. On spécifie habituellement la sortie modifiée de cqtssetup.pl ... -o Entity comme argument de l'option -f .
  3. Générez le fichier schéma de recherche Solr (-o Solr), qui indique comment les entités sont indexées. On spécifie habituellement la sortie de cqtssetup.pl ... -o CQ comme argument de l'option -f .

Cette commande est installée dans le répertoire d'installation du produit par défaut.

Options et arguments

–d nom_base_de_données
Nom de la base de données.
–s ensemble_bases_de_données
Nom de l'ensemble de bases de données.
–u utilisateur
Nom de l'utilisateur.
–p mot_de_passe
Mot de passe.
–o { Entity | CQ | Solr }
Modes de fonctionnement :
  • Entity créera un fichier d'entités.
  • CQ créera un fichier de propriétés de recherche.
  • Solr créera un fichier schéma de recherche Solr.
–f fichier_entités
Fichier d'entités. Cette option ne peut être spécifiée qu'avec les options CQ et Solr. Si cette option est omise, tous les types d'entités pouvant être soumises pour les recherches (ainsi que leurs zones), qui seront trouvées dans la base de données, seront employées en argument de la commande.

Fichier d'entités

Un fichier d'entités est généré lorsque -o Entity est indiqué comme mode de fonctionnement. Elle contiendra les entités pouvant être soumises pour les recherches, trouvées dans la base de données. Ces entités étant bien comprises par le développeur du schéma ClearQuest, toute autre explication du fichier d'entités est superflue.

Avertissement : Au minimum, les trois zones suivantes doivent être indexées pour que la fonction de recherche en texte intégral fonctionne :
  • record_type
  • dbid
  • version
L'indexation de zones supplémentaires optimise la fonction de recherche en texte intégral sans augmenter la taille de l'index de façon significative.

Fichier de propriétés de recherche ClearQuest

Un fichier de propriétés de recherche ClearQuest est généré lorsque -o CQ est indiqué comme mode de fonctionnement. Il contient plusieurs sections : search engine (moteur de recherche), database crawler (moteur de balayage), database (base de données) et entity (entité). Si la base de données ClearQuest est répliquée, il y aura plusieurs instances de chaque section. Chaque instance correspond à une réplique et peut nécessiter une configuration spécifique à la réplique.

Section Search engine

Cette section décrit les balises XML présentes dans la section Search engine du fichier CQ-nom_db-nom_ensembledb.xml. Vous trouverez ci-dessous un exemple de cette section :
<!- 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>
Spécifie la configuration utilisée pour communiquer avec le moteur de recherche. Pour une base de données non répliquée, sitename="<local>".
Si la base de données est répliquée, il y aura une instance de cette balise pour chaque réplique et la valeur de sitename indiquera le site de cette réplique. La fonction de recherche en texte intégral lira la valeur de sitename. Si cette valeur ne correspond pas au nom du site, la fonction de recherche est désactivée.
Vous n'avez pas besoin de modifier cette balise.
<searchrequest>
Spécifie l'URL du serveur du moteur de recherche, ainsi que le mode de communication avec ce serveur. Vous n'avez pas besoin de modifier cette balise.
<searchprop>
Spécifie la taille par défaut des pages et du cache.
  • pagesize spécifie le nombre d'occurrences par page.
  • cachesize spécifie le nombre d'occurrences à lire et à placer dans le cache.
Vous n'avez pas besoin de modifier cette balise.

Section Database crawler

Cette section décrit les balises XML présentes dans la section Database crawler du fichier,CQ-nom_bd-nom_ensemblebd.xml. Vous trouverez ci-dessous un exemple de cette section :

<!- 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>
La valeur de cette balise est lue par l'extracteur d'enregistrements en mode de traitement par lots ou de mise à jour. Elle indique la configuration de site à utiliser pour communiquer avec le moteur de recherche. Pour une base de données non répliquée, sitename="<local>".

Pour une base de données répliquée, il y a une balise <CQDbCrawler> distincte pour chaque réplique, chaque instance de sitename spécifiant le site de la réplique. Si la base de données est répliquée, l'extracteur d'enregistrements recherche une valeur sitename qui correspond au nom du site sur lequel il s'exécute. S'il n'en trouve pas, il ne démarre pas.

<batch>, <update>
Les valeurs de ces balises sont lues par la commande cqtsdbcrawler en mode de traitement par lots et de mise à jour. Vous pouvez modifier ces valeurs en fonction de votre environnement ClearQuest.
  • size indique le nombre d'enregistrements à lire en une seule fois, avant d'envoyer les enregistrements au moteur de recherche pour indexation.
  • delay indique le laps de temps, en secondes, que l'extracteur d'enregistrements laisse s'écouler entre deux traitements de groupes d'enregistrements de la taille spécifiée par l'option size. La valeur par défaut de l'option delay est de 600 secondes.
  • login_iteration indique quand une nouvelle session de connexion est créée. Par défaut, une nouvelle session de connexion est créée chaque fois que le délai indiqué sous delay expire. Les valeurs suivantes sont valides :
    -1
    Connectez-vous une fois et restez connecté tant que l'application s'exécute.
    0 | 1
    Comportement par défaut. Les deux valeurs ont le même effet : vous êtes connecté et déconnecté chaque fois que le processus est activé, conformément à la valeur indiquée sous delay.
    n
    Vous êtes déconnecté et connecté lorsque le processus est activé pour la nième fois, conformément à la valeur indiquée sous delay.
  • url indique comment communiquer avec le moteur de recherche pour ajouter des enregistrements à l'index.
  • thread ne s'applique qu'au mode de traitement par lots. Elle indique le nombre d'unités d'exécution à créer lors de l'exécution de requêtes. Plus le nombre d'unités d'exécution est important, plus l'extraction des enregistrements est rapide. Le nombre maximal autorisé d'unités d'exécution est de 10. Les valeurs supérieures à 10 sont tronquées à 10.
  • Mettez à jour toute référence à localhost si approprié :
    • Si votre service de recherche ClearQuest Solr s'exécute sur le même hôte que le serveur de gestion des changements, localhost suffit.
    • Si vous travaillez dans un environnement à équilibrage de charge ou réparti comprenant plusieurs serveurs de gestion des changements et un hôte pour le service de recherche ClearQuest ou que vous disposez de plusieurs bases de données utilisateur indexées à l'aide de profils de recherche ClearQuest résidant sur différents hôtes ou d'une configuration ClearQuest MultiSite dans le cadre de laquelle un service de recherche ClearQuest commun est utilisé pour gérer les requêtes pour les serveurs de gestion des changements à divers emplacements ClearQuest MultiSite, indiquez l'adresse IP ou le nom d'hôte (sous la forme d'une adresse URL) de l'hôte du service de recherche ClearQuest applicable au lieu de localhost.

Exemple

Si la valeur de login_iteration est 10 et que vous changez la valeur de delay de 600 secondes (par défaut) en 60 secondes, une nouvelle session de connexion est créée toutes les 10 minutes, tandis que les nouveaux enregistrements ClearQuest ou les enregistrements ClearQuest modifiés sont vérifiés toutes les minutes. L'index pour les recherches en texte intégral peut ainsi être plus étroitement synchronisé avec la base de données ClearQuest.

Section Database

Cette section décrit les balises XML présentes dans la section base de donnée du fichier, CQ-nom_bd-nom_ensemblebd.xml. Vous trouverez ci-dessous un exemple de cette section :

<!-- 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>
L'extracteur d'enregistrements lit la valeur de cette balise, en mode de traitement par lots et en mode de mise à jour, pour connaître la configuration de site à utiliser pour communiquer avec la base de données ClearQuest et le serveur de gestion des changements (CM), afin d'extraire les enregistrements et de surveiller les mises à jour dans la base de données. Pour une base de données non répliquée, sitename="<local>".

Pour une base de données répliquée, il y a une instance de CQDatabase pour chaque réplique, l'option sitename spécifiant le site de la réplique. L'extracteur d'enregistrements recherche une valeur sitename qui correspond au nom du site sur lequel il s'exécute. S'il n'en trouve pas, il ne démarre pas.

Vous n'avez pas besoin de modifier cette balise.

<cmserver>
Indique l'adresse URL du serveur de gestion des changements. Modifiez la valeur de cette balise de manière appropriée :
  • Si votre service de recherche ClearQuest Solr s'exécute sur le même hôte que le serveur de gestion des changements, localhost suffit.
  • Si vous travaillez dans un environnement à équilibrage de charge ou réparti comprenant plusieurs serveurs de gestion des changements et un hôte pour le service de recherche ClearQuest ou que vous disposez de plusieurs bases de données utilisateur indexées à l'aide de profils de recherche ClearQuest résidant sur différents hôtes ou d'une configuration ClearQuest MultiSite dans le cadre de laquelle un service de recherche ClearQuest commun est utilisé pour gérer les requêtes pour les serveurs de gestion des changements à divers emplacements ClearQuest MultiSite, indiquez l'adresse IP ou le nom d'hôte (sous la forme d'une adresse URL) de l'hôte du service de recherche ClearQuest applicable au lieu de localhost.
<repository>
Indique le profil de connexion à la base de données. Modifiez les valeurs suivantes en fonction de votre profil :
  • dbset indique le nom de l'ensemble de bases de données.
  • dbname indique le nom de la base de données.
  • username indique l'identité, attendue par l'extracteur d'enregistrements, de l'utilisateur qui se connecte à ClearQuest.
  • password spécifie le mot de passe chiffré généré par cqtsdbcrawler.pl.
  • keyfile spécifie le nom de chemin complet du fichier de clés servant à déchiffrer le mot de passe.
Avertissement : Vous devez spécifier une valeur valide pour username, password, et keyfile :
  • Dans un environnement de production, utilisez un mot de passe codé et un fichier de clés.
  • Dans un environnement de prototypage et de test uniquement, vous pouvez choisir de laisser le mot de passe vide et de ne pas utiliser de fichier de clés. Cependant, ce scénario ne doit pas être utilisé dans un environnement de production.

Dans le cas contraire, des erreurs se produiront à l'exécution de l'extracteur d'enregistrements cqdbtscrawler.pl en mode de traitement par lots ou en mode mise à jour.

Section Entité

Cette section décrit les balises XML présentes dans la section Entity du fichier CQ-nom_db-nom_ensembledb.xml. Vous trouverez ci-dessous un exemple de cette section :

<!- 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>
La valeur de cette balise est lue par l'extracteur d'enregistrements et par la fonction de recherche. Si la base de données ClearQuest est répliquée, les instances de CQEntity doivent être cohérentes sur tous les sites, sinon l'indexation (et donc les résultats de recherche) seront incohérents d'une réplique à une autre.
<field>
L'extracteur d'enregistrements utilise les valeurs de cette balise pour déterminer si une zone peut faire l'objet d'une indexation et d'une recherche, de la manière suivante :
  • name indique le nom de la zone.
  • index indique si la zone doit être indexée ou non. Si index="<true>", l'entité spécifiée est indexée et peut donc faire l'objet d'une recherche.
  • disp_order indique si la zone doit être affichée dans les résultats de recherche, et le cas échéant :
    • La valeur 0 signifie que la zone ne doit pas s'afficher.
    • La valeur 1 signifie que la zone doit s'afficher. Seule une zone est affichable par entité.
    Avertissement : Tous les types d'enregistrement indexés à l'aide de la fonction de recherche en texte plein ClearQuest ne doivent inclure qu'une seule zone dont la valeur de disp_order est 1. Si plusieurs zones incluent une valeur disp_order de 1, aucun résultat ne s'affiche.

Fichier schéma de recherche Solr

Le fichier schéma de recherche Solr est généré lorsque -o Solr est indiqué comme mode de fonctionnement. A l'instar du mode de fonctionnement -o CQ, celui-ci prend en entrée le fichier d'entités généré en exécutant la commande en mode Entity (-o Entity). Vous n'avez pas à éditer le fichier schéma de recherche Solr ; au lieu de cela, vous copiez des sections de celui-ci dans le fichier schéma Solr schema.xml. (Pour plus d'informations sur schema.xml, voir la documentation de Solr.)

La section la plus importante du fichier schéma de recherche Solr est la section Search engine, dont un exemple est donné ci-dessous :
<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>
Donne à Solr des informations sur l'indexation des zones :
  • name indique un nom de zone.
  • type indique le type des données.
  • indexed indique si la zone doit être indexée.
  • stored indique si les données contenues dans la zone doivent être stockées dans l'index Lucene.
  • required indique si un document doit contenir la zone (et les données qu'elle renferme) pour pouvoir être ajouté à l'index.
  • multivalued indique s'il peut y avoir une autre balise <field> de ce nom.
Ne pas modifier cette balise.
<unique_key>
Indique la zone de la définition de document Lucene qui est à utiliser comme ID document. Cette zone est lue par Solr, Lucene, l'extracteur d'enregistrements et la fonction de recherche ClearQuest pour identifier de façon unique un enregistrement ClearQuest. Ne pas modifier cette balise.
<defaultSearchfield>
Indique la zone à utiliser lorsqu'une recherche est exécutée sans qualificatif de zone. Solr et Lucene emploient cette zone pour effectuer des recherches dans toutes les zones d'un enregistrement. Ne pas modifier cette balise.
<copyField>
Indique que le contenu d'une zone doit être copié dans une autre zone, dans ce cas : <defaultSearchfield>. Ne pas modifier cette balise.

Exemples

  1. Générez un fichier de toutes les entités pouvant être soumises dans la base de données SAMPL.
    cqperl cqtssetup.pl -d SAMPL -s TextSearch -u admin -p "" -o Entity

    Cette commande générera le fichier Entity-SAMPL-TextSearch.txt. Le contenu de ce fichier étant semblable à ce qui suit :

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

    Modifiez le fichier pour indiquer les types et zones d'enregistrement dans lesquels rechercher. Par exemple, si seuls les enregistrements du type Defect doivent faire l'objet de recherches, supprimez toutes les lignes du fichier sauf celle commençant par Defect=. Si seules certaines des zones définies par ce type d'enregistrement peuvent faire l'objet de recherches, conservez uniquement ces zones en supprimant les autres. Par exemple, si seuls Headline, Description, and Severity doivent faire l'objet de recherches, le fichier édité devrait alors ressembler à ce qui suit :

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

    Notez que les zones record_type, dbid et version sont conservées. Le fait que ces trois zones soient indexées est une exigence pour la mise en oeuvre de la recherche en texte intégral.

  2. Générez un fichier de propriétés de recherche en indiquant le fichier d'entités, Entity-SAMPL-TextSearch.txt, qui a été généré par la commande précédente.
    cqperl cqtssetup.pl -d SAMPL -s TextSearch -u admin -p ""
    -o CQ -f Entity_SAMPLE_TextSearch.txt

    Cette commande génère le fichier CQ-SAMPL-TextSearch.xml, utilisé à la fois par l'extracteur d'enregistrements (cqtsdbcrawler.pl) et par la fonction de recherche.

  3. Générez un fichier schéma de recherche Solr en indiquant le fichier d'entités, Entity-SAMPL-TextSearch.txt.
    cqperl cqtssetup.pl -d SAMPL -s TextSearch -u admin -p ""
    -o Solr Entity-SAMPL-TextSearch.txt

    Cette commande générera le fichier Solr-SAMPL-TextSearch.xml. Vous n'avez pas à éditer ce fichier : copiez simplement des sections de celui-ci dans le fichier Solr, schema.xml.

  4. Mettez à jour le fichier schéma Solr, schema.xml, en remplaçant certaines sections par les sections correspondantes du fichier Solr-SAMPL-TextSearch.xml :
    1. Remplacez la section <fields> de schema.xml par la section <fields> de Solr-SAMPL-TextSearch.xml.
    2. Remplacez la section <copyfield> en suivant le même principe.
    3. Remplacez la section <uniqueKey> en suivant le même principe. Cette section est supposée déjà exister si vous êtes parti d'un fichier schema.xml existant.
    4. Remplacez la section <defaultSearchField> en suivant le même principe. Cette section est supposée déjà exister si vous êtes parti d'un fichier schema.xml existant.
  5. Redémarrez WAS pour que les changements opérés prennent effet.
Remarque : Si vous éditez votre propre schema.xml, remplacez la valeur de <field name= ... par le nom de votre schéma de base de données. Si vous utilisez ClearQuest MultiSite, indiquez le nom du site local ; par exemple, <field name="Acme Defect Tracking at Madrid"... La page web d'administration de Solr reflétera ainsi ce changement.

Voir aussi

cqtsdbcrawler.pl, setmasterpropertyfromfile


Feedback