Pacote de troca de dados

De Wiki.bireme.org/pt
Ir para: navegação, pesquisa

Para que se possa efetivar algum tipo de cooperação ou intercâmbio de serviços, seja no tratamento ou uso das informações, como no caso de BIREME e SciELO, um processo seguro de intercâmbio de dados deve ser suprido, o que resulta neste pacote de troca de dados.

Como a experiência mostrou que, o uso simplório do FTP (protocolo e ferramenta) não garante que os dados tenham a qualidade desejada após sua viagem pelos meios de comunicação, por vezes melhor seria continuar, ou concluir, determinados processamentos com um conjunto de dados desatualizado, mas não deteriorado.


Objetivos

  • Viabilizar a independência de intervenção humana nas trocas de dados entre BIREME e SciELO
  • Garantir o intercâmbio de dados livre de falhas
  • Prover o suprimento de dados mesmo na ausência de conectividade
  • Definir um protocolo de troca de dados entre entidades

Recursos e Tecnologias Necessários

  • Conexão ativa com Internet para consulta a URL http://homolog.webservices.scielo.org/scieloorg/_design/couchdb/_view/network, que reporta instâncias SciELO e seus respectivos status;
  • Servidor de FTP próprio de cada instituição (SciELO e BIREME);
  • Espaço de disco dos servidores de ao menos 100G bytes;
  • Ambiente operacional Linux (interpretador bash versao 3 ou superior);
    • Pacotes mínimos: tar; gzip; md5sum; cisis*; python (com módulo JSON).
* utilitários cisis do 'sabor' necessário em diretório que conste no 'path' da máquina

Delimitações Gerais

  • Operação humana ou automática (por crontab)
  • Rotinas de Envio e Recepção separadas (formando um pacote)
  • Arquivos de configuração (do tipo texto plano)
  • Possibilidade de uso de argumentos de chamada
  • Auto-ajuste da operação por sensoriamento de ambiente (inclusão / exclusão de diretórios de dados)

Padrões aplicáveis

São aplicáveis os padrões internos de desenvolvimento de shell-scripts, prevendo chamadas ao mecanismo de LOG (source log ou . log) e interrupção de fluxo por falha/erro de execução, além do cabeçalho padronizado no arquivo de modelo de shell existente no diretório de miscelâneas do caminho /usr/local/bireme/misc

Aplicabilidade

Este pacote poderá ser utilizado em duas situações de troca de dados a saber:

  1. trocas de dados entre BIREME e SciELO;
  2. trocas de dados entre SciELO e componentes de sua rede.

Para tanto basta efetuar ajustes no arquivo de configuração anteriormente citado.

Atualmente emprega-se Envia2Medline.bat para efetuar parte do descrito aqui e será substituído por envia2ORG.sh, que passará a ser parte integrante do pacote de distribuição.

Descrição do Protocolo Básico

O protocolo de envio e recepção de pacotes de dados a ser implementado tem por objetivo garantir a entrega de dados do enviador para o recebedor, de tal forma que se alguma disfunção no processo ocorrer, e for possível detectá-la, o último pacote de dados enviado com sucesso será entregue no lugar do atual, ficando assim garantida a operação dos processos onde se inclue a recepçao de dados pelo uso deste protocolo.

Para tanto uma sequência de ações deve ser executada de cada lado do meio de transmissão. São tarefas do enviador:

  1. Verificar se o diretório de destino existe;
    1. Caso não exista deve cria-lo;
  2. Testar se no diretório de destino o semáforo "IN-USE" está ativo;
    1. Caso esteja, testar esta condição até "X" (configurável) vezes;
      1. Caso continue "IN-USE" termina a execução com saída de erro;
  3. Eliminar (caso exista) o semáforo "DATA-READY";
  4. Para cada item da "SEND-LIST" gerar um arquivo MD5;
  5. Empacotar os componentes da lista de envio com os arquivos MD5 gerados em um tar-ball compactado (tgz);
  6. Escrever o tar-ball compactado no diretório do servidor de ftp;
  7. Ativar o semáforo "DATA-READY";
  8. Fim de tarefa de envio.

São tarefas do recebedor:

  1. Testar se existe o diretório esperado para receber os dados (informado por parâmetro de chamada);
    1. Caso não exista termina a execução com saída de erro;
  2. Testa se existe semáforo "DATA-READY" ativo no diretório
    1. Caso não exista, testar esta condição até "Y" (configurável) vezes;
      1. Caso continue não existindo termina execução com saída de erro;
  3. Ativar semáforo "IN-USE"
  4. Elimina o flag "DATA-READY" (não implementado por haver dois receptores de dados);
  5. Le o tar-ball compactado disponível no diretório;
  6. Após a leitura do tar-ball compactado, eliminar o semáforo "IN-USE";
  7. Descompactar e abrir o tar-ball;
  8. Testar o MD5 de cada componente recebido;
    1. Aqueles que tiverem resultado Ok devem ser enviados para o servidor de ftp em subdiretório específico para reserva de dados;
    2. Aqueles que tiverem resultado Nok devem ser eliminados e subtituídos pelos correspondentes encontrados no subdiretório de reserva de dados existente no servidor de ftp.

Interface de Usuário

Como chamadas de linha de comando podem ser utilizadas opções e parâmetros nas chamadas tanto do envio quanto da recepção de dados, como se observa na sintaxe a seguir:

Envio de Dados

 envia2.sh [[-h|--help]|[-v|--version]|[-c config_file]] <Sigla3_SciELO> <arquivo_controle>

envia2.sh : script-shell que desempenha todas as tarefas de envio de pacote de dados, como cálculo de MD5 e empacotamento compactado em arquivo tar

opções:
 -h | --help    - tela de ajuda para uso do comando
 -v | --version - exibe a versão do comando em execução, sua data e responsável
 -c <arquivo>   - aplica as configurações do arquivo indicado ao invés daquelas do arquivo padrão (vaivem.conf)

parâmetros:
 Sigla3_SciELO    - (mandatório) uma das diversas siglas de três letras que identificam instâncias do SciELO
                    (scl=Brasil; spa=Saúde Pública; sss=Social Sciences; sza=África do Sul; ...)
 arquivo_controle - (mandatório) arquivo texto com o nomes dos arquivos a serem enviados, um por linha

Recepção de Dados

 recebf.sh [[-h|--help]|[-v|--version]|[-c config_file]] <Sigla3_SciELO>

recebf.sh : script-shell que desempenha todas as tarefas de recebimento de pacote(s) de dados, com descompactação e desempacotamento de arquivo tar mais a conferência de MD5

opções:
 -h | --help    - tela de ajuda para uso do comando
 -v | --version - exibe a versão do comando em execução, sua data e responsável
 -c <arquivo>   - aplica as configurações do arquivo indicado ao invés daquelas do arquivo padrão (vaivem.conf)

parâmetros:
 Sigla3_SciELO - (mandatório) uma das diversas siglas de três letras que identificam instâncias do SciELO
                 (scl=Brasil; spa=Saúde Pública; sss=Social Sciences; sza=África do Sul; ...)

Plano de Desenvolvimento

O desenvolvimento do par de rotinas será dividido em três etapas:

  • Etapa 1 - Comando de Envio de Dados;
  • Etapa 2 - Comando de Recepção de Dados;
  • Etapa 3 - Atividades complementares.

Etapa 1 - Comando de Envio de Dados

O desenvolvimento do comando de envio de dados teve três (3) fases (cada qual com sua bateria de testes funcionais):

  • Fase 1 - implementação de funções acessórias;
  • Fase 2 - núcleo básico de empacotamento;
  • Fase 3 - automação de envio.

Fase 1 - Implementação de funções acessórias

Aqui foram implementadas as capacidades de interpretação de opções, ou seja, utilização de um arquivo de configuração diverso do padrão por omissão (vaivem.conf), exibição de ajuda ao uso do comando, além do exibidor de versão.

Fase 2 - Núcleo Básico de Empacotamento

Nesta fase ocorre a interpretação do parâmetro dois da chamada (Arquivo Lista de Controle: 'arquivo_controle') que indica as peças de dados a serem enviadas, testa a disponibilidade das peças, calcula o MD5 de cada uma, empacota e compacta o conjunto de dados.

Fase 3 - Automação de Envio

Nesta fase foi contemplada a interpretação do parâmetro 1 (um) da chamada (instância alvo) a conexão ftp, envio do pacote de dados, e garantia de colocação em servidor.

Estado Atual

Em 29 de junho de 2.011 foi dado como concluído o desenvolvimento das rotinas de envio de dados face ao teste conjunto com as rotinas de recepção.

(Em 20 de junho de 2.011 foi dado como concluído o desenvolvimento das rotinas relacionadas com o envio de dados, restando aguardar a conclusão do desenvolvimento das rotinas de recepção para iniciar testes funcionais massivos (teste de stress).)

Etapa 2 - Comando de Recepção de Dados

O desenvolvimento do comando de envio de dados teve cinco (5) fases (cada qual com sua bateria de testes funcionais):

  • Fase 1 - interpretação de opções;
  • Fase 2 - delimitação de instância;
  • Fase 3 - recepção de pacotes;
  • Fase 4 - desempacotamento dos dados;
  • Fase 5 - ativação da reserva de dados e sinalização de saída.

Fase 1 - Interpretação de Opções

Aqui foram implementadas (por reprodução do pacote de envio, respeitadas as diferenças devidas) as capacidades de interpretação de opções, ou seja utilização de um arquivo de configuração diverso do padrão por omissão (vaivem.conf), exibição de ajuda ao uso do comando, além do exibidor de versão.

Fase 2 - Delimitação de Instância

Nesta fase ocorre a interpretação do parâmetro da chamada (Sigla3_SciELO) que limita a recepção de pacote de dados a instância especificada na chamada.

Fase 3 - Recepção de Pacotes

Nesta fase foi contemplada a recepção de pacote da instância avaliada como devida na Fase 2. Toda a sinalização e tratamento de semáforos foi contemplada aqui.

Fase 4 - Desempacotamento dos Dados

Nesta fase foram providas verificações de descompressão de dados com sucesso, conferência de códigos MD5 e comparação com dados do último conjunto recebido com sucesso.

Fase 5 - Ativação da Reserva de dados e Sinalização de Saída

Conforme a Fase 4 determine o pacote de dados como válido, estes são gravados na reserva e o código de retorno com sucesso é provido. Se por outro lado a Fase 4 determina o pacote de dados como não válido serão tomados da reserva o último conjunto ali gravado e o código de retorno com erro é provido.

Estado Atual

Em 29 de junho de 2.011 foi dado como concluído o desenvolvimento das rotinas de recepção e efetuada bateria de testes em conjunto com as rotinas de envio de dados.

(Em 21 de junho de 2.011 será iniciado o desenvolvimento das rotinas de recepção de dados, para posterior teste modular e então teste funcional massivo em conjunto com as rotinas de envio.)

Etapa 3 - Atividades complementares

O desenvolvimento das atividades complementares (montagem de chamadas pré-configuradas; documentação complementar; empacotamento; teste geral nas máquinas 'destino'; etc.) resultou nas seguintes chamadas para uso final:

  • bir2sci.sh - enviador de dados no sentido BIREME -> SciELO
  • envia2ORG.sh - substituto da atual Envia2Medline.bat
  • envia2.sh - enviador de dados genérico configurado por default para o sentido SciELO -> rede
  • recebf.sh - receptor de dador genérico
  • seguro.sh - codificador de arquivo de senhas
  • segura.sh - decodificador de arquivo de senhas para base de dados CDS-ISIS (para fins de verificação)

Resultou também no documento README.1st que descreve tecnicamente os componentes do pacote de troca de dados via FTP, e finalmente no arquivo tar-ball compactado tr_x.tgz que contém todas as partes e componentes necessários para a implantação do pacote.

Implantação e Configuração

As instruções aqui contidas são mínimas e não têm a pretensão de substituir um manual técnico para o pacote, mas sim servir de guia rápido para colocar em uso o pacote.

Implantação

Ao tomar o tar-ball (tr_x.tgz) do pacote este deve ser aberto e seus componentes devem ser transferidos para o diretório de uso, nos termos das rotinas praticadas em Operação de Fontes de Informação, tipicamente, num tpl.xxx. Por princípio, todos os componentes devem estar em um mesmo diretório e não podem (sem customização dos shell-scripts) ser separados em diferentes diretórios.

A única operação a ser realizada que se assemelha a uma instalação (além da cópia referida) é a recriação de um Master-File (M/F) da base de dados gizmo denominada gunians que deve ser efetuada com o utilitário id2i do CISIS como mostra o comando a seguir (assumindo que os utilitários do CISIS estão no path de execução da máquina):

id2i gunians.id create=gunians

Configuração

A configuração do pacote é simples e baseada em um arquivo texto sem formatação (plain text file), seguindo o estilo de arquivo de configuração empregado no Apache, onde temos uma declaração (statment) associando um termo a um valor através de um sinal de igualdade (TERMO = valor). Comentários podem permear o arquivo como forma de documentação se desejado, mas não são obrigatórios, assim como as próprias declarações são opcionais assumindo, em caso de ausência, valores default, previamente, programados nos shell-scripts.

Termos para uso no Arquivo de Configuração (case-sensitive)
Termo Explanação valor Default Limites / Escopo
PY Permite o uso de lescielos.py (mais rápido) (não declarado) TRUE ou não declarado
HOSTSERVER Identificação do servidor de execução do comando SciELO BIREME / SciELO / NETWORK
TXTIMO Número máximo de tentativas para controlar o canal de transmissão 31 valor inteiro maior que zero
RXTIMO Número máximo de tentativas para obter leitura de data-ready no canal de recepção 6 valor inteiro maior que zero
TXSERVER URL do servidor de FTP usado no canal de transmissão ftp.scielo.br qqr URL de FTP válida
RXSERVER URL do servidor de FTP usado no canal de recepção ftp.scielo.br qualquer URL de FTP válida
TXUSER Username para conexão ao servidor FTP de envio usr.bireme qualquer username válido
TXPASS Password do usuário do servidor FTP de envio 123deoliveira4 qualquer senha válida
RXUSER Username para conexão ao servidor FTP de recepção joao.silva qualquer username válido
RXPASS Password do usuário do servidor FTP de recepção b!r3n3 qualquer senha válida
USER Username para conexão ao servidor FTP (transmissão e recepção) jane.doe qualquer username válido
PASS Password do usuário do servidor FTP (transmissão e recepção) #s3nh@f0rt3! qualquer senha válida

No pacote estão contidos oito (8) arquivos de configuração, identificados pela extensão .conf (não obrigatória), que podem/devem ser tomados como exemplos para a criação de outros arquivos de configuração, na utilização do pacote de troca de dados via FTP.

Abaixo é mostrado o conteúdo do arquivo de configuração vaivem.conf, que é o arquivo assumido na falta de indicação de outro específico, pela utilização da opção -c na chamada do shell-script de envio ou de recepção de dados:

# Categoria de servidor executando o servico de troca de dados (TX ou RX)
HOSTSERVER = SciELO

# Time-out para a tentativa de envio com 'canal' ocupado em segundos
TXTIMO = 31

# Time-out para tentativa de recepcao com 'canal' indisponivel em segundos
RXTIMO = 6

# Endereco do servidor de FTP a ser utilizado
TXSERVER = ftp.scielo.br
RXSERVER = ftp.scielo.br

Conclusão

Ao término do ciclo de desenvolvimento será enviado um e-mail para a "lista OFI" dando ciência da conclusão da tarefa e início da vida útil do produto do desenvolvimento com sua inclusão na sistemática de versionamento da instituição.