Labarchive Integration

Integração LabArchives

Visão Geral

LabArchives é uma plataforma de caderno eletrônico de laboratório para documentação de pesquisa e gerenciamento de dados. Acesse cadernos, gerencie entradas e anexos, gere relatórios e integre com ferramentas de terceiros de forma programática via REST API.

Quando Usar Esta Skill

Esta skill deve ser usada quando:

• Trabalhar com REST API do LabArchives para automação de cadernos
• Fazer backup de cadernos de forma programática
• Criar ou gerenciar entradas e anexos de cadernos
• Gerar relatórios de site e análises
• Integrar LabArchives com ferramentas de terceiros (Protocols.io, Jupyter, REDCap)
• Automatizar upload de dados para cadernos eletrônicos de laboratório
• Gerenciar acesso de usuários e permissões de forma programática

Capacidades Principais

1. Autenticação e Configuração

Configure credenciais de acesso à API e endpoints regionais para integração com LabArchives API.

Pré-requisitos:

• Licença enterprise LabArchives com acesso à API habilitado
• ID de chave de acesso e senha da API fornecidos pelo administrador LabArchives
• Credenciais de autenticação do usuário (email e senha de aplicações externas)

Configuração de setup:

Use o script scripts/setup_config.py para criar um arquivo de configuração:

python3 scripts/setup_config.py

Isso cria um arquivo config.yaml com a seguinte estrutura:

api_url: https://api.labarchives.com/api  # ou endpoint regional
access_key_id: YOUR_ACCESS_KEY_ID
access_password: YOUR_ACCESS_PASSWORD

Endpoints regionais de API:

• EUA/Internacional: https://api.labarchives.com/api
• Austrália: https://auapi.labarchives.com/api
• Reino Unido: https://ukapi.labarchives.com/api

Para instruções de autenticação detalhadas e resolução de problemas, consulte references/authentication_guide.md.

2. Recuperação de Informações do Usuário

Obtenha ID do usuário (UID) e informações de acesso necessárias para operações subsequentes de API.

Fluxo de trabalho:

1. Chame o método de API users/user_access_info com credenciais de login
2. Analise a resposta XML/JSON para extrair o ID do usuário (UID)
3. Use o UID para recuperar informações detalhadas do usuário via users/user_info_via_id

Exemplo usando wrapper Python:

from labarchivespy.client import Client

# Initialize client
client = Client(api_url, access_key_id, access_password)

# Get user access info
login_params = {'login_or_email': user_email, 'password': auth_token}
response = client.make_call('users', 'user_access_info', params=login_params)

# Extract UID from response
import xml.etree.ElementTree as ET
uid = ET.fromstring(response.content)[0].text

# Get detailed user info
params = {'uid': uid}
user_info = client.make_call('users', 'user_info_via_id', params=params)

3. Operações de Caderno

Gerencie acesso a cadernos, backup e recuperação de metadados.

Operações-chave:

• Listar cadernos: Recupere todos os cadernos acessíveis para um usuário
• Fazer backup de cadernos: Baixe dados completos de cadernos com inclusão opcional de anexos
• Obter IDs de cadernos: Recupere identificadores de cadernos definidos pela instituição para integração com sistemas de gestão de projetos/bolsas
• Obter membros do caderno: Liste todos os usuários com acesso a um caderno específico
• Obter configurações do caderno: Recupere configuração e permissões para cadernos

Exemplo de backup de caderno:

Use o script scripts/notebook_operations.py:

# Backup com anexos (padrão, cria arquivo 7z)
python3 scripts/notebook_operations.py backup --uid USER_ID --nbid NOTEBOOK_ID

# Backup sem anexos, formato JSON
python3 scripts/notebook_operations.py backup --uid USER_ID --nbid NOTEBOOK_ID --json --no-attachments

Formato de endpoint de API:

https://<api_url>/notebooks/notebook_backup?uid=<UID>&nbid=<NOTEBOOK_ID>&json=true&no_attachments=false

Para documentação abrangente de métodos de API, consulte references/api_reference.md.

4. Gerenciamento de Entradas e Anexos

Crie, modifique e gerencie entradas de cadernos e anexos de arquivo.

Operações de entrada:

• Criar novas entradas em cadernos
• Adicionar comentários a entradas existentes
• Criar partes/componentes de entrada
• Upload de anexos de arquivo para entradas

Fluxo de trabalho de anexos:

Use o script scripts/entry_operations.py:

# Upload de anexo para uma entrada
python3 scripts/entry_operations.py upload --uid USER_ID --nbid NOTEBOOK_ID --entry-id ENTRY_ID --file /path/to/file.pdf

# Criar uma nova entrada com conteúdo de texto
python3 scripts/entry_operations.py create --uid USER_ID --nbid NOTEBOOK_ID --title "Resultados do Experimento" --content "Resultados do experimento de hoje..."

Tipos de arquivo suportados:

• Documentos (PDF, DOCX, TXT)
• Imagens (PNG, JPG, TIFF)
• Arquivos de dados (CSV, XLSX, HDF5)
• Formatos científicos (CIF, MOL, PDB)
• Arquivos (ZIP, 7Z)

5. Relatórios de Site e Análises

Gere relatórios institucionais sobre uso de cadernos, atividade e conformidade (recurso Enterprise).

Relatórios disponíveis:

• Relatório de Uso Detalhado: Métricas de atividade do usuário e estatísticas de engajamento
• Relatório Detalhado de Caderno: Metadados do caderno, listas de membros e configurações
• Relatório de Geração de Caderno PDF/Offline: Rastreamento de exportação para conformidade
• Relatório de Membros do Caderno: Controle de acesso e análises de colaboração
• Relatório de Configurações do Caderno: Auditoria de configuração e permissões

Geração de relatório:

# Generate detailed usage report
response = client.make_call('site_reports', 'detailed_usage_report',
                           params={'start_date': '2025-01-01', 'end_date': '2025-10-20'})

6. Integrações de Terceiros

LabArchives integra-se com numerosas plataformas de software científico. Esta skill fornece orientação sobre o aproveitamento dessas integrações de forma programática.

Integrações suportadas:

• Protocols.io: Exporte protocolos diretamente para cadernos LabArchives
• GraphPad Prism: Exporte análises e figuras (Versão 8+)
• SnapGene: Integração direta de workflow de biologia molecular
• Geneious: Exportação de análise de bioinformática
• Jupyter: Incorpore notebooks Jupyter como entradas
• REDCap: Integração de captura de dados clínicos
• Qeios: Plataforma de publicação de pesquisa
• SciSpace: Gerenciamento de literatura

Autenticação OAuth: LabArchives agora usa OAuth para todas as novas integrações. Integrações legadas podem usar autenticação de chave de API.

Para instruções detalhadas de setup de integração e casos de uso, consulte references/integrations.md.

Fluxos de Trabalho Comuns

Fluxo de trabalho completo de backup de caderno

1. Autentique e obtenha ID do usuário
2. Liste todos os cadernos acessíveis
3. Itere através de cadernos e faça backup de cada um
4. Armazene backups com metadados de timestamp

# Script de backup completo
python3 scripts/notebook_operations.py backup-all --email user@example.edu --password AUTH_TOKEN

Fluxo de trabalho de upload automático de dados

1. Autentique com API LabArchives
2. Identifique caderno e entrada de destino
3. Faça upload de arquivos de dados experimentais
4. Adicione comentários de metadados a entradas
5. Gere relatório de atividade

Exemplo de fluxo de trabalho de integração (Jupyter → LabArchives)

1. Exporte notebook Jupyter para HTML ou PDF
2. Use entry_operations.py para fazer upload para LabArchives
3. Adicione comentário com timestamp de execução e informações de ambiente
4. Marque entrada para fácil recuperação

Instalação de Pacote Python

Instale o wrapper labarchives-py para acesso simplificado de API:

git clone https://github.com/mcmero/labarchives-py
cd labarchives-py
uv pip install .

Alternativamente, use requisições HTTP diretas via biblioteca requests do Python para implementações customizadas.

Melhores Práticas

1. Rate limiting: Implemente atrasos apropriados entre chamadas de API para evitar throttling
2. Tratamento de erros: Sempre envolva chamadas de API em blocos try-except com logging apropriado
3. Segurança de autenticação: Armazene credenciais em variáveis de ambiente ou arquivos de configuração seguros (nunca em código)
4. Verificação de backup: Após backup de caderno, verifique integridade e completude do arquivo
5. Operações incrementais: Para cadernos grandes, use paginação e processamento em lotes
6. Endpoints regionais: Use o endpoint regional correto de API para desempenho otimizado

Resolução de Problemas

Problemas comuns:

• 401 Unauthorized: Verifique se ID de chave de acesso e senha estão corretos; confirme se acesso à API está habilitado para sua conta
• 404 Not Found: Confirme que ID de caderno (nbid) existe e usuário tem permissões de acesso
• 403 Forbidden: Verifique permissões do usuário para a operação solicitada
• Resposta vazia: Certifique-se de que parâmetros obrigatórios (uid, nbid) são fornecidos corretamente
• Falhas de upload de anexo: Verifique limites de tamanho de arquivo e compatibilidade de formato

Para suporte adicional, contate LabArchives em support@labarchives.com.

Recursos

Esta skill inclui recursos agrupados para suportar integração com LabArchives API:

scripts/

• setup_config.py: Gerador de arquivo de configuração interativo para credenciais de API
• notebook_operations.py: Utilitários para listar, fazer backup e gerenciar cadernos
• entry_operations.py: Ferramentas para criar entradas e fazer upload de anexos

references/

• api_reference.md: Documentação abrangente de endpoint de API com parâmetros e exemplos
• authentication_guide.md: Instruções detalhadas de setup de autenticação e configuração
• integrations.md: Guias de setup de integração de terceiros e casos de uso