Exibir código-fonte para IAHx - Interface de busca integrada

= Descrição = 

== O que é ==

É um serviço de busca robusta e eficiente, com interface multi-idioma, que permite localizar informação em Ciências da Saúde de várias fontes de informação tecno-científicas, utilizando diversos filtros para refinamento de resultados, inclusive por terminologia do [[DeCS]]<sup>1</sup>, permitindo visualizá-los de forma integrada, individualizada, tipificada e ordenada.

== Objetivo ==

Integrar, concentrar e uniformizar resultados de busca de diversas fontes de informação em um modelo único de referência e permitir acesso ao documento de texto completo (se e quando existente), além de outros recursos como salvamento e/ou exportação em diversos formatos.

== Principais funcionalidades ==

* Interface integrada para toda a coleção de fontes de informação da [http://modelo.bvsalud.org/ BVS]<sup>2</sup>, independente de seu tipo;
* Disponibilização do resultado da busca em uma lista única, com distribuição por clusters (conjuntos ou grupos);
* Opção de busca por tipo de fonte de informação, por campo de busca específico e/ou por fonte de Informação; 
* Organização do resultado da busca por relevância, data do documento, ordem alfabética, fator de impacto da revista e outros;
* Formato de apresentação do resultado da busca de modo homogêneo e padronizado, independente do tipo de fonte, com opções para formato detalhado e links para serviços disponíveis, tais como texto completo, serviço de fotocópia, currículo de autor, entre outros;
* Registro do histórico de buscas;
* Recursos de RSS da busca;
* Recursos "Social Bookmarking".

== Público-alvo ==

'''Uso da interface'''

Profissionais técnicos e de gestão da área de saúde, pesquisadores e acadêmicos do ensino superior na área de biomédicas.

'''Uso da tecnologia'''

Profissionais de tecnologia (Analistas de Sistemas, Analistas de Suporte, Administradores de Sistemas etc).

= Informações Gerais = 

== Como funciona ==

'''Arquitetura do Sistema'''

[[Arquivo:ArquiteturaSistema.jpg]]

[[Arquivo:Arquitetura2.jpg]]

'''Arquitetura de Tecnologia da BVS'''

[[Arquivo:ArquiteturaTecnologicaBVS.jpg]]

== Status ==

Ativo. Estável.

== Categoria ==

Interfaces de busca

== Forma de distribuição ==

Serviço web ([http://pesquisa.bvsalud.org/ Interface de busca integrada da BVS]<sup>3</sup>).

Aplicação para servidor ([[IAHx_-_Interface_de_busca_integrada#Reposit.C3.B3rio|Repositório de código]]).

== Classificação ==

Interface de busca.

== Tipo de Licença ==

LGPL (GNU Less General Public License). Para mais informação acesse o site do [http://www.gnu.org/licenses/lgpl.html LGPL]<sup>4</sup>.

= Características técnicas  = 

== Plataforma ==

PC Linux server

== Conhecimentos necessários ==

* Sistema operacional Linux
* Shell Script (bash)
* Servidor WEB (Apache HTTPd<sup>5</sup>)
* Apache TomCat<sup>6</sup>
* Noções de SOA<sup>7</sup>
* Java<sup>8</sup>
* Apache SOLR/Lucene<sup>9</sup>
* PHP<sup>10</sup>
* xHTML<sup>11</sup>
* XML<sup>12</sup>
* CSS<sup>13</sup>

== Software requerido ==

* Java versão 7.x
* Apache Tomcat 6.x
* Apache 2
* PHP 5.5.x
* SOLR/Lucene (*)

(*) Incluído no IAHx server.

== Ambiente operacional utilizado == 

=== Linguage(m/ns) utilizada(s) ===

* PHP
* Shell script (bash)
* Java
* JavaScript
* CSS
* XML

=== Framework(s) ===

* PHP Silex<sup>14</sup>

=== Persistência de dados ===

* Índice binário do Apache Lucene.

= Canais de comunicação = 

O IAHx é distribuido no padrão ''open source'' cujo suporte ocorre através da Comunidade RedDes. Para participar basta preencher o formulário de inscrição disponível na [http://listas2.bireme.br/cgi-bin/mailman/listinfo/reddes Lista da Comunidade RedDes].

= Repositório =
 
Código fonte  disponível a partir do repositório GitHub<sup>15</sup> - BIREME/PAHO/WHO.
* https://github.com/bireme/

No repositório GIT são disponibilizadas pacotes em formato GIT (com controle de versionamento), arquivos compactados em formatos ZIP e TAR.GZ, além de tags fechadas (releases anteriores do código). As instruções para baixar e instalar os pacotes encontram-se disponíveis na seção '''[[IAHx_-_Interface_de_busca_integrada#Instala.C3.A7.C3.A3o_e_configura.C3.A7.C3.A3o|Instalação e configuração]]''' deste documento.

== Pacotes atualizados (GIT, tar.gz, ZIP ) ==

* [http://github.com/bireme/iahx-server IAHx-Server]
* [http://github.com/bireme/iahx-data IAHx-Data]
* [http://github.com/bireme/iahx-controller IAHx-Controller]
* [http://github.com/bireme/iahx-opac IAHx-OPAC]

== Releases anteriores ==

* [http://github.com/bireme/iahx-server/releases IAHx-Server]
* [http://github.com/bireme/iahx-data/releases IAHx-Data]
* [http://github.com/bireme/iahx-controller/releases IAHx-Controller]
* [http://github.com/bireme/iahx-opac/releases IAHx-OPAC]

= Documentação =

== Instalação e configuração ==

Os passos a seguir foram criados a partir da instalação do software prerrequisito e dos aplicativos IAHx utilizando um equipamento servidor com SO  Ubuntu<sup>16</sup> 14.04 LTS 32 bits (GNU/Linux 3.13.0-24-generic i686). Pode ser utilizado Ubuntu 12.x ou superior, 32 ou 64 bits.

Em geral, o Apache web server já encontra-se instalado por default no Ubuntu. Caso não esteja, siga as instruções de instalação de pacotes para sua distribuição. Para informação mais detalhada sobre o Apache web server acesse http://httpd.apache.org/.

NOTAS INICIAIS:
* Os exemplos de instalação de pacotes de software prerrequisito para IAHx citados são baseados no SO Linux Ubuntu;
* O pacote 'build-essential' deve ser instalado no Ubuntu antes de iniciar qualquer instalação de software prerrequisito para o IAHx;
* Sugere-se seguir o modo de instalação padrão para cada distribuição de modo a manter a compatibilidade dos software prerrequisitos;
* Serão explicitadas quaisquer peculiaridades relativas ao Ubuntu que podem não se aplicar ao SO de sua preferência.

=== Software prerrequisito ===

==== Java 7 ====

Instale e configure o Java (testado até versão 7.x).
* Link geral para o [http://www.java.com/en/download/ Java versão 7.x].
* Links específicos de referência para SO Ubuntu: [http://www.webupd8.org/2012/01/install-oracle-java-jdk-7-in-ubuntu-via.html Install Oracle Java SDK7 in Ubuntu] e [http://www.ubuntugeek.com/how-to-install-oracle-java-7-in-ubuntu-12-04.html How to install Oracle Java 7 in Ubuntu].

1. Remova a instalação default do Java (específico para Ubuntu).

<pre>apt-get purge openjdk*</pre>
 
NOTA: Em Ubuntu, verifique antes se o pacote 'software-properties-common' está instalado. Ele é necessário para o próximo passo. Senão, utilize a linha abaixo.

<pre>apt-get install software-properties-common</pre>

2. Instale o pacote Java 7 (deve conter JRE e JDK).

<pre>add-apt-repository ppa:webupd8team/java
apt-get update
apt-get install oracle-java7-installer</pre>
 
3. Verifique o status da instalação.

<pre>java -version</pre>

==== Tomcat 6 ====

Instale e configure o servidor de aplicações Tomcat (testado até a versão 6.x).
* Link geral para o [http://tomcat.apache.org/ Tomcat 6.x].

1. Instale o Tomcat 6.

<pre>apt-get install tomcat6</pre>

2. Edite o arquivo de configuração do Tomcat, habilite a variável JAVA_HOME e altere adequadamente o conteúdo da variável com o PATH da instalação do Java 7.

<pre>vi /etc/default/tomcat6</pre>

3. Reinicie o serviço do Tomcat.

<pre>service tomcat6 restart</pre>

4. Verifique se o Tomcat está executando corretamente abrindo um navegador web e acessando o endereço padrão do servidor (por exemplo: localhost) adicionando ao final a identificação da porta 8080.

<pre>http://localhost:8080/</pre>

NOTA: o resultado deve ser uma página informando que o Tomcat foi configurado com sucesso.

5. Se desejar usar os aplicativos de gerenciamento do Tomcat via web, instale o pacote do Admin. O nome do pacote é mostrado no resultado de execução da URL onde o Tomcat está instalado. No Ubuntu é ''tomcat6-admin''.

<pre>apt-get install tomcat6-admin</pre>

Em seguida, edite o arquivo de configuração para incluir os usuários que tem permissão para acessar os aplicativos de gerenciamento via web. Veja detalhes de como editar este arquivo na documentação do Tomcat. Em seguida, salve o arquivo e reinicie o serviço do Tomcat.

<pre>vi /etc/tomcat6/tomcat-users.xml
service tomcat6 restart</pre>

Para testar acesse o endereço do Tomcat no navegador e acrescente ao final ''manager/html''.

<pre>http://localhost:8080/manager/html</pre>

[[Arquivo:Image002.jpg]]

==== PHP 5 ====

A instalação do PHP 5 assume que já esteja instalado e executando um servidor web (ex. Apache 2) na porta default (80). Caso não esteja instalado, leia o tópico [[IAHx_-_Interface_de_busca_integrada#Apache_HTTPd_server_2|Apache HTTPd Server 2]] a seguir antes de instalar o PHP 5.

Instale e configure o PHP para servir páginas dinâmicas do servidor (testado até a versão 5.5).
* Link geral para o [http://php.net/ PHP 5.5].

<pre>apt-get install php5</pre>

Para verificar se o PHP está executando corretamente, crie um arquivo com extensão 'php' no DOCUMENT_ROOT do servidor Apache.

<pre>vi /var/www/html/info.php</pre>

Digite o seguinte conteúdo:

<pre><?php phpinfo(); ?></pre>

Salve o arquivo e abra um navegador web. No campo de endereço digite o domínio do servidor sem a identificação da porta.

<pre>http://localhost/info.php</pre>

O resultado será uma página com toda configuração do PHP instalado. Se não conseguir ver esta página, revise os passos de instalação.

[[Arquivo:Sem_título.jpg]]

==== Apache HTTPd server 2 ====

Dependendo da forma como o SO Linux Ubuntu foi instalado, e também da distribuição utilizada, o Apache HTTPd server 2 pode não estar disponível.

A versão testada como SO Linux Ubuntu 14 foi Apache 2.4. Para mais informação acesse a página do projeto [http://httpd.apache.org/ Apache HTTPd]. 

Para verificar se já existe uma versão de Apache instalado no servidor, digite:

<pre>whereis apache2</pre>

Em geral, a resposta será algo como:

<pre>apache2: /usr/sbin/apache2 /etc/apache2 /usr/lib/apache2 /usr/share/apache2</pre>

Caso não tenha sido instalado (a lista de localização está vazia), instale-o utilizando o comando abaixo:

<pre>aptitude -y install apache2</pre>

Há dois modos para verificar que o Apache está ativo:

* na linha de comando, digite:

<pre>ps aux | grep apache</pre>

ou

* abra uma janela do navegador de internet de sua preferência e digite o nome do domínio referente aquele servidor:

<pre>http://localhost/</pre>

NOTAS:
* Os comandos acima assumem o uso de SO Linux Ubuntu 14;
* O Apache HTTPd server assume IP 127.0.0.1 e domain 'localhost' por padrão;
* Cada distribuição vem com pacotes testados e homologados para aquela distro Linux e podem ter sido configurados com módulos e opções diferentes. Verifique sempre a documentação de sua distribuição em caso de dúvidas ou problemas com instalação de pacotes e configuração de módulos de aplicativos.

=== Pacotes IAHx ===

Instale os pacotes do iAHx (Server, Processamento, Controller e OPAC) de acordo com sua preferência.

* Utilizando GIT para garantir versionamento (modo preferível):
** Torna mais fácil a atualização do software para o administrador de sistema;
* Realizando download dos pacotes compactados:
** Apesar de trazer o código mais atualizado do repositório de aplicações, dificulta a atualização dos módulos.

Nos passos de instalação dos módulos do IAHx são documentadas as duas formas de instalação (por GIT ou pacote compactado). O usuário deve optar por uma ou outra.

==== Instalando software GIT ====

Se optar por esta opção o usuário deverá instalar o software git no servidor antes de inicar a instalação dos pacotes com opção de versionamento.

Para instalar o  GIT e todas as dependências necessárias, execute a linha abaixo:

<pre>apt-get -f install git</pre>

NOTA: o modo de instalação e sintaxe do gerenciador de pacotes pode variar entre distribuições Linux e até mesmo entre versões de uma mesma distribuição.

==== Baixando os módulos do IAHx ====

1. Crie o diretório para a instalação dos módulos do IAHx (ex.: /home/apps/iahx/);

<pre>mkdir -p /home/apps/iahx</pre>

2. Garanta que o cursor esteja no diretório raiz de instalação dos módulos;

<pre>cd /home/apps/iahx/</pre>

3. Acesse o repositório de software da Bireme no GitHub (https://github.com/bireme/) para baixar os pacotes dos módulos do IAHx no diretório criado no passo 1:

a. IAHx-Server:

 http://github.com/bireme/iahx-server/archive/master.tar.gz

b. IAHx-Processamento:

 http://github.com/bireme/iahx-data/archive/master.tar.gz

c. IAHx-Controller:

 http://github.com/bireme/iahx-controller/archive/master.tar.gz

d. IAHx-OPAC:

 http://github.com/bireme/iahx-opac/archive/2.0.tar.gz

NOTAS: Os nomes de arquivos relativos aos pacotes referem-se à última versão disponível (em desenvolvimento). Caso o usuário prefira uma versão ou release específico, basta procurar em '''tags''' pela versão desejada, a partir dos nomes dos módulos.

* Ex.:

 http://github.com/bireme/iahx-server/tags/

==== Instalando o IAHx-Server ====

1. Se o diretório para a instalação dos módulos do IAHx (ex.: /home/apps/iahx/) ainda não tiver sido criado, crie-o como demonstrado a seguir;

<pre>mkdir -p /home/apps/iahx</pre>

2. Garanta que o cursor esteja no diretório raiz de instalação dos módulos;

<pre>cd /home/apps/iahx/</pre>

3. Instale o módulo IAHx-Server:

a. Utilizando GIT:

<pre> git clone git://github.com/bireme/iahx-server.git iahx-server</pre>

b. Descompactando o módulo IAHx-server:

<pre>tar xvzpf iahx-server-master.tar.gz</pre>

'''NOTA''': Após descompactar o nome do diretório deverá ser renomeado de ''iahx-server-master'' para ''iahx-server''.

4. Inicie o servidor IAHx-server (SOLR):

<pre>cd iahx-server/bin/

 ./server1.sh start</pre>

5. Verificar se o módulo servidor está em execução através do navegador:

<pre>http://seu-dominio:8981/solr/admin/</pre>

onde 'seu-dominio' deve ser trocado pelo correspondente à sua instalação, podendo ser um domínio ou IP. Veja como está configurado seu web server (Apache).

[[Arquivo:Image001.jpg]]

NOTAS: Sempre que o servidor for reinicializado, o passo 4 deverá ser repetido para garantir que o IAHx-Server está em execução. Também pode ser colocado em crontab de usuário, preferencialmente um que não tenha direitos para comandos 'sudo'; ou em profile de usuário específico, também com direitos reduzidos. A decisão de qual maneira utilizar (manual, automático, em cron ou em profile) fica a critério do administrador de sistemas.

==== Instalando o IAHx-Data (Processamento) ====

1. Garanta que está no diretório de instalação dos módulos do IAHx (/home/apps/iahx/):

<pre>cd /home/apps/iahx/</pre>

2. Instale o módulo IAHx-Data:

a. Utilizando GIT:

<pre>git clone git://github.com/bireme/iahx-data.git iahx-data</pre>

b. Descompactando o módulo IAHx-Data:

<pre>tar xvzpf iahx-data-master.tar.gz</pre>

'''NOTA''': Após descompactar o nome do diretório deverá ser renomeado de ''iahx-data-master'' para ''iahx-data''.

==== Instalando o IAHx-Controller ====

1. Garanta que está no diretório de instalação dos módulos do IAHx (/home/apps/iahx/):

<pre>cd /home/apps/iahx/</pre>

2. Instale o módulo IAHx-Controller:

a. Utilizando GIT:

<pre>git clone git://github.com/bireme/iahx-controller.git iahx-controller</pre>

b. Descompactando o módulo IAHx-Controller:

<pre>tar xvzpf iahx-controller-master.tar.gz</pre>

'''NOTA''': Após descompactar o nome do diretório deverá ser renomeado de ''iahx-controller-master'' para ''iahx-controller''.

3. Realize o deployment em seu servidor Tomcat (porta 8080):    

a. Acesse o Tomcat Web Application Manager:

<pre>http://servidor-tomcat:8080/manager/html</pre>

[[Arquivo:Image002.jpg]]

b. Procure na página o quadro ''Deploy'' e na seção ''Deploy directory or WAR file located on server'' preencha os campos abaixo com os valores indicados:

* Context Path (required): Indica o diretório do módulo IAHx-Controller.

<pre>/iahx-controller</pre>

* WAR or Directory URL: Indica o caminho físico do arquivo iahx-controler.war.

<pre>/home/apps/iahx/iahx-controller/dist/iahx-controller.war</pre>

* Clique no botão ''Deploy''.

[[Arquivo:Image003.jpg]]

c. Verifique se o resultado da execução disponibilizou uma linha no quadro ''Applications'' para o IAHx-controller.

[[Arquivo:Image004.jpg]]

==== Instalando o IAHx-OPAC (Interface) ====

1. Garanta que está no diretório de instalação dos módulos do IAHx (/home/apps/iahx/):

<pre>cd /home/apps/iahx/</pre>

2. Instale o módulo IAHx-OPAC:

a. Utilizando GIT:

<pre>git clone git://github.com/bireme/iahx-opac.git iahx-opac</pre>

b. Descompactando o módulo IAHx-OPAC:

<pre>tar xvzpf iahx-opac-2.0.tar.gz</pre>

'''NOTA''': Após descompactar o nome do diretório deverá ser renomeado de ''iahx-opac-2.0'' para ''iahx-opac''.

3. Crie um Virtual Host no Apache para a aplicação conforme exemplo abaixo:

<pre> <VirtualHost *:80>
    ServerAdmin admin@localhost
    ServerName search.local
    DirectoryIndex index.htm index.php homepage.htm
    DocumentRoot "/home/apps/iahx/iahx-opac/"
    <Directory "/home/apps/iahx/iahx-opac/">
               AllowOverride All
               Options FollowSymLinks MultiViews
               Require all granted
    </Directory>
 </VirtualHost></pre>

4. Reinicialize o Apache para garantir que o novo Virtual Host esteja ativo:

<pre>service apache2 restart</pre>

5. Crie o diretório '''logs''' abaixo de '''iahx-opac''':

<pre>mkdir -p /home/apps/iahx/iahx-opac/logs</pre>

6. Altere as permissões para do diretório para permitir que o usuário do Apache possa escrever os logs de uso do módulo:

<pre>cd /home/apps/iahx/iahx-opac

 chmod -R 777 logs</pre>

7. Mude o cursor para o diretório dos arquivos de configuração do módulo IAHx-OPAC:

<pre>cd /home/apps/iahx/iahx-opac/config</pre>

8. Copie o arquivo '''config-mail-SAMPLE.php''' para '''config-mail.php'''.

<pre>cp config-mail-SAMPLE.php config-mail.php</pre>

9. Copie o arquivo '''config-SAMPLE.xml''' para '''config.xml'''.

<pre>cp config-SAMPLE.xml config.xml</pre>

10. Teste o uso da interface acessando a URL do ServerName definido no passo anterior no navegador web de sua preferência:

<pre>http://search.local/</pre>

O resultado deve ser a página de busca sem conteúdo, uma vez que é a configuração padrão do pacote.

[[Arquivo:Image005.jpg]]

NOTA: O serviço de DNS deve ser alterado adequadamente para permitir a localização do ServerName - do Virtual Host definido no passo 3 -  via web.

=== Configurando os pacotes do IAHx ===

Os arquivos do sistema IAHx já vêm previamente configurados com valores padrão que permitem utilizar prontamente as rotinas de processamento, realizando um mínimo de parametrização. Por padrão o PATH base para os pacotes do IAHx está configurado como '''/home/apps/iahx''' e o nome da instância como '''default'''. Embora estando configurado, a instância vem com o índice zerado, exigindo assim que o usuário realize o primeiro processamento com dados de teste de uma base LILACS com 203 registros afim de testar se o processamento, a interface e a comunicação entre os vários módulos está correta e funcional.

==== Configuração de parâmetros dos módulos IAHx para processamento, gestão de dados e disponibilização ====

Os arquivos e respectivas configurações são:

* iahx-server/instances/1/conf/Catalina/localhost/default-main.xml
** atributo ''value'' do elemento ''Environment'': '''${catalina.home}/../../indexes/default/main'''
* iahx-opac/config/config.xml
** elemento ''site'': '''default'''
** elemento ''bvs_url'': http://my-bvs/
** elemento ''about_bvs_url'': http://my-bvs/
** elemento ''home_url'': http://'''search.local'''/
** elemento ''search_server'': localhost:8080
** elemento ''name'': '''main'''
* iahx-data/exec/tabs/iAHx.tab
** diretório raiz dos índices: '''/home/apps/iahx/iahx-server/indexes'''
** ID da instância: '''default'''
** nome do índice: '''default-main'''
** nome da instância: '''default'''
** diretório do processamento: '''default/main'''
** diretório do índice: '''default/main'''
** URL disponível: '''search.local'''

Todos os locais assinalados acima devem ser revisados caso o usuário tenha instalado os pacotes do IAHx em caminhos diferentes, afim de refletir a realidade do servidor.

Os diretórios com dados e processos relativos a esta configuração padrão encontram-se distribuidos em:

* iahx-server/indexes/'''default/main'''/
* iahx-data/proc/'''default/main'''/

No caso de se criar uma nova instância, por exemplo '''novo-main''', o usuário deverá criar em ambos diretórios a estrutura de diretórios correspondente ('''novo/main'''). Também deverá ser instalado outro módulo IAHx-OPAC para disponibilizar a busca na nova instância.

==== Configurando arquivos necessários ao processamento e disponibilização dos dados ====

1. Garanta que está no diretório do módulo IAHx-Data (processamento):

<pre>cd /home/apps/iahx/iahx-data/</pre>

2. Edite o arquivo '''ambiente''' e altere os caminhos (PATH) nas variáveis de acordo com a estrutura de diretórios de sua instalação;

NOTA: Veja as implicações destas alterações em relação aos outros arquivos do sistema.

3. Grave o arquivo '''ambiente''' em '''/usr/local/bireme/misc'''. Se este diretório ou árvore de diretórios não existir, crie-o com o comando abaixo:

<pre>mkdir -p /usr/local/bireme/misc</pre>

4. Garanta que as variáveis JAVA_HOME e JRE_HOME foram definidas durante a instalação do Java. Caso não tenham sido definidas, inclua ambas na inicialização de variáveis globais do servidor para todos os usuários:

<pre>export JRE_HOME=/usr/lib/jvm/java-7-oracle/jre
 export JAVA_HOME=/usr/lib/jvm/java-7-oracle</pre>

NOTA: a localização de diretórios do Java pode variar de acordo com a distribuição, as várias versões das mesmas e também dos pacotes de instalação.

5. Garanta que o caminho para os arquivos binários do Java tenha sido definido na variável global PATH do ambiente do servidor para todos os usuários. Caso não tenha sido definido, faça-o antes de prosseguir com a configuração do ambiente:

<pre>export PATH=${PATH}:${JAVA_HOME}/bin</pre>

NOTA: Para que as variáveis estejam disponíveis será necessário realizar um novo login no sistema.

== Processamento ==

=== Visão geral ===

NOTA: Esta modelagem de processamento assume a hospedagem de um único servidor para todo o sistema IAHx.

Componentes do processamento:
* Depósito de entrada de dados
* Árvores de diretórios de controle de processamento
* Árvore do índice processado
* Tabela de configuração de processamento
* Rotinas do pacote do servidor
* Rotinas de controle do processamento

==== Depósito de Entrada de Dados ====

O Depósito de entrada de dados é uma pasta (ou diretório) onde ser deposita(m) o(s) arquivo(s) XML de entrada no processamento.  Ele(s) deve(m) estar em conformidade com o schema referido na documentação no item XYZ.

Uma variável de ambiente (PATH_INPUT) conterá o caminho absoluto para este diretório de forma a permitir que o mesmo se localize em qualquer árvore de diretórios do sistema de arquivos do servidor.

NOTA: Caso disponha de uma base de dados CDS/ISIS em conformidade com a metodologia LILACS, encontra-se disponível no repositório do IAHx no github (https://github.com/bireme/iahx-data/blob/master/proc/default/main/resources/) um conjunto de arquivos de formato para gerar o XML de entrada do processamento IAHx a partir de tal base de dados.

==== Árvores de diretórios de controle processamento ====

Nas variáveis de ambiente PATH_EXEC e PATH_PROC temos os endereços absolutos de duas árvores componentes do processamento de IAHx, sendo a primeira o local dos elementos de processamento comuns a qualquer índice e/ou instância a ser processada, e a segunda o local dos elementos específicos de processamento de determinado índice ou instância.

Assim na árvore de PATH_EXEC encontramos:
* programas em Java;
* shell-scripts;
* arquivos de inclusão;
* tabelas de configuração;
* arquivos de mensagem para e-mail automático; e
* um arquivo de log relativo a inicio de processamento.

Já na árvore de PATH_PROC encontramos: uma sub-árvore para cada índice ou instância, composta por sua vez de um diretórios para armazenamento de logs de execução por data, diretório de dados de processamento locais, e um shell-script para coordenação de chamadas de processamento particulares do índice ou instância.

==== Árvores de índice processado ====

Na variável de ambiente INDEX_ROOT está o caminho absoluto para a árvore que congrega cada árvore de índice processado as quais contém dois ramos, um com as configurações do índice (admin-extra.html; protwords.txt; schema.xml; scripts.conf; solrconfig.xml; stopwords.txt; sunonyms.txt; export-xml.xsl; e related_query.xsl) e outro com o índice propriamente dito.

==== Tabela de configuração de processamento ====

Constituída de uma linha para cada índice ou instância, cada qual composta por 36 colunas, das quais as primeiras 15 são utilizadas no processamento e 10 são reservadas para uso futuro. Seus conteúdos são gravados em função das necessidades do processamento do índice a primeira coluna é o identificador único do índice ou instância.
* Coluna 1 - ID_INDICE – Identificador único de índice
* Coluna 2 - NM_INDICE – Nome do índice para uso do SOLR
* Coluna 3 - NM_INSTANCIA – Nome legível da instância
* Coluna 4 - DIR_PROCESSAMENTO – Diretório de processamento relativo a PATH_PROC
* Coluna 5 - DIR_INDICE – Diretório com o índice, caminho relativo ao abaixo
* Coluna 6 - RAIZ_INDICES – Topo da árvore com os índices
* Coluna 7 - SRV_TESTE – Hostname do servidor de teste [fixo vazio]
* Coluna 8 - HOMOLOG APP – Hostanme do servidor de homologação de aplicação
* Coluna 9 - HOMOLOG D – Hostname do servidor de homologação de dados [fixo .]
* Coluna 10 - PRODUCAO – Hostname do servidor de produção [fixo .]
* Coluna 11 - IAHX-SERVER – Instância de servidor IAHx para o índice [fixo em 1]
* Coluna 12 - DIR_INBOX – caminho relativo a PATH_INPUT para os dados de entrada
* Coluna 13 - NM_LILDBI – URL para a(s) base(s) em LILDBI-Web desta fonte [fixo vazio]
* Coluna 14 - SITUACAO – Status de índice ativo ou não [fixo SIM]
* Coluna 15 - PROCESSA – Status de processamento validado [fixo SIM]
* Colunas 16 a 25 - Reservadas
* Coluna 26 - TIPOPROC – Automático ou manual
* Coluna 27 - PERIODICIDADE – Intervalo de processamento dos dados
* Coluna 28 - NM_PORTAL – Nome do portal onde se encontra o índice
* Coluna 29 - URL_DISPONIVEL – URL disponível para acesso público
* Coluna 30 - URL – Endereço Internet para acesso ao OPAC
* Coluna 31 - PARAMETRO URL – Parâmetros complementares para acesso ao OPAC
* Coluna 32 - IDIOMAS – Versões idiomáticas para tradução de legendas
* Coluna 33 - VRS – Versão da interface OPAC
* Coluna 34 - OBSERVAÇÃO – Observações em geral sobre o índice
* Coluna 35 - WIKI_EXPRESSAO – URL para as expressões de seleção de dados na Wiki
* Coluna 36 - LST_FISIDX - ????

==== Rotinas do pacote do servidor ====

São dez rotinas que compõe o pacote do servidor, conforme listadas a seguir:

# checkerror  - Verificação de erro de operação
#* parm1 – Return Code a testar
#*  parm2 – String com a mensagem de erro
# commit2homolog.sh – Assumção do índice em homologação
#* vide command help (-h)
# commit.sh – Assumção local do índice
#* vide command help (-h)
# deletedocs.sh – Eliminação de documentos do índice prévio 
#* vide command help (-h)
# index.sh – Indexação de dados 
#* vide command help (-h)
# optimize.sh – Otimização de índice de IAHx 
#* vide command help (-h)
# psx – process status of IAHx 
#* vide command help (-h)
# reinicia_iAHx.sh – Reiniciação dos servidores IAHx
#* sem parâmetros
# srviahx.sh – serviço IAHx 
#* vide command help (-h)
# wdtiAHx.sh – Watch-Dog-Timer IAHx
#* sem parâmetros

Todos os scripts, exceto checkerror contam com a opção -h para exibir instruções de uso resumidas.

==== Rotinas de controle do processamento ====

São sete rotinas que compõe o pacote de controle de processamento, conforme listadas a seguir:

# 0-processa-inbox.sh – Tratamento dos dados no depósito de entrada
#* Vide command help (-h)
# 1-index.sh – Coordenador de indexação dos XMLs presents em ‘xml.index’
#* Vide command help (-h)
# cron_weekly3.sh – Escalador de execução por agendamento
#* Vide command help (-h)
# enviaDados.sh – Transferência de dados para servidor de produção/homologação
#* Vide command help (-h)
# update-index.sh – Coordenador de processamento de índice/instância
#* Vide command help (-h)
# index-weekly.sh – Tratamento para coleta e indexação de dados de dada instância
#* Vide command help (-h)
# EnviadorDeEmail.jar – Programa JAVA para envio de e-mail
#* Vide exemplo de uso em cron_weekly3.sh

Todos os shell-scripts suportam a opção -h para exibir instruções de uso resumidas.

Cada índice/instância tem sua própria versão (no local, ou seja, diretório de processamento) do script index-weekly.sh, adaptável para as necessidades específicas do índice/instância.

Cada índice/instância pode ter sua própria versão de pré-tratamento de dados (no local, ou seja, diretório de procfessamento), adaptável conforme suas necessidades específicas.

Cada índice/instância pode ter sua própria versão de coordenador de indexação (no local, ou seja, diretório de procfessamento), adaptável conforme suas necessidades específicas.

=== Executando o processamento ===

1. Antes de iniciar qualquer processamento dos dados para o IAHx é necessário equalizar o ambiente operacional. Isto é feito pelo comando abaixo, assumindo que a configuração tenha sido feita adequadamente.

<pre>source /usr/local/bireme/misc/ambiente</pre>

2. Edite o arquivo iAHx.tab e altere quaisquer caminhos (PATH) e/ou dados que reflitam a situação de sua instância. O arquivo encontra-se pré-configurado com a instância '''default'''.

3. Iniciar o processamento utilizando a linha abaixo, a partir do diretório da instância que se deseja processar (padrão para /home/apps/iahx/iahx-data/proc/default/main).
 
<pre>$PATH_EXEC/update-index.sh <INDICE></pre>

NOTAS:
* iAHx.tab permite definir várias instâncias de processamento - uma instância por linha -, utilizando o mesmo módulo ''iahx-data'';
* O arquivo iAHx.tab deve ser editado com cuidado;
* A separação entre as colunas é feita pelo caractere ''TAB'' (0x09);
* Para mais detalhes sobre o arquivo iAHx.tab, leia o item '''Processamento - Visão Geral'''.

=== Validando o resultado do processamento ===

Após o processamento, o site indicado no campo ''URL Disponível'' do arquivo iAHx.tab, pode ser utilizado no navegador web para verificar a disponibilização dos dados, os clusters, as opções de bases de dados etc.

[[Arquivo:Image006.jpg]]

Para mais informação sobre o uso da interface de busca, por favor, acesse o tópico [[IAHx_-_Interface_de_busca_integrada#Uso_da_interface_de_busca|Uso da Interface de Busca]] deste documento.

== Uso da interface de busca ==

O uso da interface de busca do Portal Regional é explicado no [http://wiki.bireme.org/pt/index.php/Tutorial_de_pesquisa Tutorial de busca integrada]. Esta informação também está disponível em [http://wiki.bireme.org/pt/index.php/Videos_tutoriais_de_pesquisa videos tutorias de busca integrada].

Para a elaboração de estratégias de busca e refinamentos de busca mais elaborados sugerimos ler o documento "[http://wiki.bireme.org/pt/index.php/Elabora%C3%A7%C3%A3o_de_estrat%C3%A9gias_de_busca Elaboração de estratégias de busca]".

= Apêndices =

== Apêndice I - Documentação histórica ==

=== Documentos relacionados ===

* [http://wiki.reddes.bvsalud.org/index.php/IAHx_-_Recupera%C3%A7%C3%A3o_de_informa%C3%A7%C3%A3o_baseada_em_clusters Recuperação de informação baseada em clusters]

* [http://wiki.reddes.bvsalud.org/index.php/Definicao_Schema_das_fontes_de_informa%C3%A7%C3%A3o Definição do Schema das fontes de informação]

=== Mockup de página web ===

[[Arquivo:Mockup.jpeg|Mockup]]

Primeiro desenho gráfico com arquitetura da informação sugerida para a página de resultados da busca integrada.

=== WBS do projeto ===

[[Arquivo:Wbs-pesquisa.jpg|WBS do projeto]]

Estrutura analítica do projeto (WBS).

=== Protótipo ===

[[Arquivo:Tela_resultado.jpg|Protótipo]]

Protótipo da página de resultados da busca integrada.


=== Mockup para mobile ===

[[Arquivo:01-iAHx-mobile.jpg|800px]]

[[Arquivo:02-iAHx-mobile.jpg|800px]]

== Apêndice II - Integração com BVS-Site ==

=== Script para redirecionar pesquisa do portal para o iAHx ===

1. Criar abaixo do diretório '''htdocs/apps/''' da instalação do '''BVS-Site''' o diretório '''iahx/''' e criar neste último o arquivo '''index.php''' com o seguinte conteúdo: 

<pre><?php
    $iahx_url = "http://pesquisa.bvsalud.org/";
    $iahx_url .= "?" . $_SERVER['QUERY_STRING'];
    header("Location: " . $iahx_url);
?></pre>

2. Alterar o endereço da URL para o site de busca integrada próprio:

<pre>$iahx_url = "http://search.local/";</pre>

=== Ajustando o formulário de busca da BVS para usar o script de redirecionamento ===

1. Editar o arquivo '''metasearch.xsl''' localizado em '''xsl/public/components/''' abaixo do diretório de instalação do '''BVS-Site'''. Deve ser criado ou alterado o '''template metasearch''' conforme exemplo abaixo:

<pre><xsl:template match="metasearch">
	<div id="search" style="display: block;">
		<h3>
			<span><xsl:value-of select="text[@id = 'search_title']" /></span>
		</h3>
		<form name="searchForm" action="/apps/iahx/" method="get">
			<input type="hidden" name="lang"   value="{$lang}" />
			<input type="hidden" name="_charset_"  value="" />

			<div class="searchItens">
				<xsl:apply-templates select="text[@id = 'search_entryWords']" /><br />
				<input type="text" name="q" class="expression" />
				<input type="submit" value="{text[@id = 'search_submit']}" name="submit" class="submit" />
			</div>
		</form>
	</div>
</xsl:template></pre>

2. Abrir a administração do '''BVS-Site''', entrar na edição de metapesquisa e gravar.

Caso seja necessário adicionar no formulário de busca para o iAHx os índices e fontes disponíveis na busca, adicione no template acima os seguintes elementos:

<pre><div class="searchItens">
	<xsl:apply-templates select="text[@id = 'search_entryWords']" /><br />
	<input type="text" name="q" class="expression" />
 
        <select class="inputText mini" name="index">
            <option selected="true" value=""><xsl:value-of select="text[@id = 'all_indexes']" /></option>
            <option value="ti"><xsl:value-of select="text[@id = 'index_title']" /></option>
            <option value="au"><xsl:value-of select="text[@id = 'index_author']" /></option>
            <option value="mh"><xsl:value-of select="text[@id = 'index_subject']" /></option>
        </select>
        &#160;<xsl:value-of select="text[@id = 'search_where']" />:
        <select class="inputText mini" name="where">
            <option value="ALL"><xsl:value-of select="text[@id = 'all_sources']" /></option>
            <option value="LILACS"><xsl:value-of select="text[@id = 'source_lilacs']" /></option>
            <option value="MEDLINE"><xsl:value-of select="text[@id = 'source_medline']" /></option>
            <option value="WHOLIS"><xsl:value-of select="text[@id = 'source_wholis']" /></option>
            <option value="H1N1"><xsl:value-of select="text[@id = 'source_h1n1']" /></option>
            <option value="SITES"><xsl:value-of select="text[@id = 'source_lis']" /></option>
        </select>
        
        <input type="submit" value="{text[@id = 'search_submit']}" name="submit" class="submit" />
    </div></pre>

A tradução para o nome de cada uma das fontes apresentadas deve ser adicionada no arquivo '''metasearch.xml''', no diretório '''bases/site/xml/[idioma]/ '''.

== Apêndice III - Tópicos avançados de configuração do IAHx ==

Esta seção visa informar o usuário operador do IAHx sobre as possibilidades de alteração dos parâmetros utilizados pela interface de busca, opções de refinamento, ordenação e apresentação de resultados de busca, e traduções de mensagens da interface.

=== Campos de busca ===

Para criar novos campos de busca é necessário adicionar estes novos elementos do tipo '''<field>'''  no arquivo de configuração do índice '''schema.xml''' abaixo do diretório '''conf''' do local de instalação do módulo server do IAHx. (ex. /home/apps/iahx/iahx-server/bvs/local/conf/schema.xml). 

<pre><fields>
   <field name="id" type="string" indexed="true" stored="true"/>
   <field name="db" type="string" indexed="true" stored="true"/>
   <field name="bvs" type="string" indexed="true" stored="true"/>
   <field name="type" type="string" indexed="true" stored="true"/>
   <field name="au" type="text" indexed="true" stored="true" multiValued="true"/>
   <field name="ti" type="text" indexed="true" stored="true" multiValued="true"/>
   <field name="ab" type="text" indexed="false" stored="true" multiValued="true"/>
   <field name="tl" type="string" indexed="true" stored="true" multiValued="true"/>
   <field name="fo" type="text" indexed="false" stored="true" multiValued="true"/>
   <field name="la" type="string_lower" indexed="true" stored="true" multiValued="true"/>
   <field name="la_ab" type="string_lower" indexed="false" stored="true" multiValued="true"/>
   <field name="ur" type="string" indexed="false" stored="true" multiValued="true"/>
   ...
</fields></pre>

Consulte a [http://wiki.apache.org/solr/SchemaXml documentação oficial do SOLR] para mais detalhes sobre este tipo de configuração.

Para ajustar a lista de índices que são apresentados na interface de busca é preciso alterar o elemento '''<index_list>''' do arquivo de configuração '''dia-config.xml''' disponível na pasta '''config''' do diretório de instalação do módulo IAHx-OPAC (ex. /home/apps/iahx/iahx-opac/config/dia-config.xml)

<pre><index_list>
     	<index>
           <!-- Nome para tradução -->
           <name>ALL</name>
	   <!-- Índice igual ao declarado no arquivo schema.xml  -->
          <prefix></prefix>
        </index>
     	<index>
	    <!-- Nome para tradução -->
            <name>TI</name>
	    <!-- Índice igual ao declarado no arquivo schema.xml  -->
            <prefix>ti</prefix>
        </index>
     	<index>
	   <!-- Nome para tradução -->
           <name>AU</name>
           <!-- Índice igual ao declarado no arquivo schema.xml  -->
           <prefix>au</prefix>
        </index>
     	<index>
	    <!-- Nome para tradução -->
            <name>LA</name>
	    <!-- Índice igual ao declarado no arquivo schema.xml  -->
            <prefix>la</prefix>
        </index>
</index_list></pre>

=== Ordenação do resultado de busca ===

Para configurar as opções disponibilizadas na interface para ordenação do resultado é necessário ajustar o elemento '''<sort_list>''' do arquivo de configuração '''dia-config.xml''' disponível na pasta '''config''' do diretório de instalação do módulo IAHx-OPAC (ex. /home/apps/iahx/iahx-opac/config/dia-config.xml)

<pre><sort_list>
          <sort>
              <name>RELEVANCE</name>
              <value>score desc</value>
          </sort>
          <sort>
             <!-- Ordem crecente de data. Esse valor de esta no arquivo de tradução -->
             <name>YEAR_ASC</name>
	     <!--dp_range é um índice de data-->
             <value>dp_range asc</value>
          </sort>
          <sort>
             <!-- Ordem crecente de data. Esse valor de esta no arquivo de tradução -->
             <name>YEAR_DESC</name>
	     <!--dp_range é um índice de data-->
             <value>dp_range desc</value>
          </sort>
</sort_list></pre>

=== Opções de refinamento (clusters) ===

Para configurar os elementos definidos no '''schema.xml''' que serão apresentados como filtros na busca é necessário ajustar o arquivo '''solrconf.xml''' que fica abaixo do diretório do índice do módulo IAHx-server (ex.  /home/apps/iahx/iahx-server/bvs/local/conf/solrconf.xml)

Os elementos definidos no arquivo '''schema.xml''' que forem utilizados como opção de refinamento devem ser declarados na lista de parâmetros do elemento '''<lst name="invariants"> usando como nome o prefixo facet seguido de ponto e o nome do elemento previamente registrado no schema.xml. 

Para registrar o elemento '''type''' como um valor de refinamento é necessário criar o seguinte elemento na lista:
 
<pre><str name="facet.field">type</str></pre>

Lembrando que o elemento type deve estar previamente registrado no arquivo schema.xml na lista de fields com um tipo string:

<pre><fields>
   ...
   <field name="type" type="string" indexed="true" stored="true"/>
   ...
</fields>

  <requestHandler name="standard" class="solr.StandardRequestHandler">
    <!-- default values for query parameters -->
     <lst name="defaults">
       <str name="echoParams">explicit</str>
     </lst>  
     <lst name="invariants">
	 <str name="facet">true</str>
	 <str name="facet.field">type</str>
         <str name="facet.field">clinical_aspect</str>
         <str name="facet.field">fulltext</str>
         <str name="facet.field">type_of_study</str>
	 <str name="facet.field">mh_cluster</str>
	 <str name="facet.field">limit</str>
	 <str name="facet.field">ta_cluster</str>
	 <str name="facet.field">la</str>
	 <str name="facet.field">year_cluster</str>
	 <str name="facet.limit">20</str>
	 <str name="facet.mincount">1</str>
     </lst>
  </requestHandler>
</pre>

Para mais informações sobre Clusters usando Solr, por favor veja a documentação oficial do projeto no tópico [http://wiki.apache.org/solr/SolrFacetingOverview SOLR Faceting Overview].

'''Nota:''' Após qualquer ajuste nos arquivos de configuração do Solr (schema.xml e solrconfig.xml) é necessário reiniciar o serviço '''IAHx-Server'''

=== Apresentação do resultado de busca ===

O módulo de busca do IAHx utiliza o mecanismo de templates [http://http://www.smarty.net/ Smarty] para construir as páginas do resultado, para alterar o formato de apresentação dos documentos ou o layout do módulo de busca é preciso alterar os arquivos que ficam no diretório '''templates''' abaixo do diretório de instalação do módulo IAHx-OPAC (ex. /home/apps/iahx/iahx-opac/templates)

Principais templates utilizados na interface de busca:

* '''top-header.tpl'''  monta o o elemento head do html contendo a inclusão de arquivos javascript e css utilizados na apresentação
* '''top-banner.tpl'''  logotipo e banner da interface
* '''top-searchbar.tpl''' caixa de busca

* '''result-clusters.tpl''' responsável por montar a coluna com as opções de refinamento
* '''result-doc.tpl'''  apresenta os documentos na lista de resultado
* '''result-detail.tpl'''  apresenta a página de detalhe de um documento

* '''bottom.tpl''' - rodapé das páginas 

=== Traduções e mensagens disponíveis na interface de busca ===

As mensagens e traduções utilizadas na apresentação da interface de busca encontram-se na pasta '''languages''' abaixo do diretório de instalação do módulo IAHx-OPAC do sistema. (ex. /home/apps/iahx/iahx-opac/languages/). O sistema inclui inicialmente os diretórios para textos em português (/languages/pt), em espanhol (languages/es) e inglês (languages/en) divididos em dois arquivos:

* texts.ini: mensagens e textos relacionadas com a interface (título da página, rótulo dos botões, etc)
* texts-local.ini : mensagens e textos relacionados com o índice (valores de refinamento, rótulo dos campos da base de dados, etc)

Os arquivos de tradução são do tipo [http://en.wikipedia.org/wiki/INI_file Arquivos INI] contendo chaves, valores e seções conforme modelo abaixo:

<pre>
 TITLE="BVS - Literatura Científico-Técnica"
 KEYWORDS="artigos científicos, saúde"
 DESCRIPTION="busca Biblioteca Virtual em Saúde"
 SEARCH_WORDS=Entre uma ou mais palavras

 [INDEXES]

 ALL=Todos os índices
 TI=Título
 AU=Autor
 MH=Assunto
 PT=Tipo de publicação

 [WHERE]

 ALL=Todas as fontes
 GENERAL=Ciências da Saúde em Geral
 LILACS=LILACS
 IBECS=IBECS
</pre>

== Apêndice IV - Outros recursos ==

* Apresentações
** [[File:BVS5-iAHx-VHL_integrated_search.ppt|Apresentação IAHx - Pesquisa Avançada na BVS5]]

* Videos
** [http://www.youtube.com/watch?v=BXXBKIAv_Xk|IAHx: Search Interface using Apache Solr/Lucene]

= Referências =

# DeCS (Descritores em Ciências da Saúde). [http://wiki.bireme.org/pt/index.php/DeCS]
# BVS (Biblioteca Virtual em Saúde). [http://modelo.bvsalud.org/]
# Interface de busca da BVS. [http://pesquisa.bvsalud.org/]
# LGPL (GNU Less General Public License). [http://www.gnu.org/licenses/lgpl.html]
# Apache HTTPd Server. [http://httpd.apache.org/]
# Apache TomCat. [http://tomcat.apache.org/]
# SOA (Service-oriented architecture. [http://en.wikipedia.org/wiki/Service-oriented_architecture]
# Java. [https://www.java.com/en/]
# Apache SOLR/Lucene. [http://lucene.apache.org/solr/]
# PHP (Hypertext Preprocessor). [http://php.net/]
# xHTML (eXtensible HyperText Markup Language). [http://xhtml.com/en/xhtml/reference/]
# XML (eXtensible Markup Language). [http://www.w3.org/XML/]
# CSS (Cascading Style Sheet). [http://www.w3.org/Style/CSS/]
# Silex. [http://silex.sensiolabs.org/]
# GitHub. [https://github.com/]
# Ubuntu. [http://www.ubuntu.com/]
# Cluster Analysis (from Wikipedia). [http://en.wikipedia.org/wiki/Cluster_analysis]
# Faceted Classification (from Wikipedia). [http://en.wikipedia.org/wiki/Faceted_classification]
# How to Make a Faceted Classification and Put It On the Web (from Miskatonic University Press). [https://www.miskatonic.org/library/facet-web-howto.html]
# Yippy (Clusty). [http://en.wikipedia.org/wiki/Yippy]


[[Category:BVS]]
[[Category:Aplicativos]]
[[Category:IAHx]]
[[Category:RST]]
[[Category:Fontes de Informação]]