Configurar o conector genérico de sincronização de dados

SmartOSH dispõe de um módulo de importação e sincronização que permite carregar dados em massa através de um ficheiro de intercâmbio (Excel ou CSV) depositado num servidor FTP. Este documento descreve o formato, a nomeação e a configuração necessária para usar o conector genérico.

Formatos de ficheiro suportados

Excel (XLS / XLSX)

O ficheiro de dados pode ser entregue em formato Microsoft Excel (.xls ou .xlsx). Neste formato, cada tabela é representada como um separador (folha) dentro do mesmo livro. Os nomes e a ordem dos separadores devem coincidir com os descritos na especificação de campos.

CSV

Também pode ser usado CSV, com um ficheiro por cada tabela. Regras obrigatórias:

• Delimitador: ;
• Carácter de escape para textos literais: aspas duplas "
• Codificação: UTF-8
• Primeira linha: nomes das colunas

Exemplo:

Codigo;Nombre;TipoIdentificacion;Identificador
001;ACME S.A.;0;A554668987
002;"LUSIANA S.A";0;A00046879

Fotografias de empregado (opcional)

O ficheiro opcional de fotografias deve ser entregue como ZIP com as imagens na diretoria raiz, com extensão .jpg, .gif ou .png.

Nomeação dos ficheiros

O nome deve começar sempre por KB020 e incluir, separados por hífen, os dados básicos do ficheiro.

Excel (XLS/XLSX)

Padrão: KB020-ORDEN-Nome descritivo.xlsx

Exemplo: KB020-1000-Carga datos MiEmpresa 20170622.xlsx

CSV

Como há um ficheiro por tabela, o nome deve incluir o nome da tabela em vez do descritivo. O prefixo numérico garante que sejam carregados pela ordem correta.

Exemplos:

• KB020-100-Empresas.csv
• KB020-200-Centros.csv
• KB020-300-Secciones.csv
• KB020-400-Puestos.csv
• KB020-500-Empleados.csv
• KB020-600-Asignaciones.csv
• KB020-700-InvestigacionAccidente.csv
• KB020-800-Formaciones.csv
• KB020-900-Convocatorias.csv
• KB020-1000-Convalidaciones.csv
• KB020-1100-SesionesFormativas.csv
• KB020-1200-AccionesFormativas.csv
• KB020-1300-Cargo.csv
• KB020-1400-AsignacionCargo.csv

Sistemas legacy com nomes curtos

Se por limitações técnicas o cliente não puder usar nomes longos, pode entregar os ficheiros com nome curto e adicionar um ficheiro index.txt na raiz da pasta com as equivalências.

Formato de cada linha: [nomecurto];[nomelongo]

Exemplo:

emp.csv;KB020-100-Empresas.csv
cen.csv;KB020-200-Centros.csv
secci.csv;KB020-300-Secciones.csv

Localização do ficheiro (FTP)

O cliente deve depositar os ficheiros num servidor FTP. Existem duas opções:

• FTP seguro próprio do cliente (FTP, FTPS ou SFTP).
• FTP seguro fornecido pelo Smart OSH (solicitando à equipa de consultoria).

Se for usado o serviço do Smart OSH, os dados de conexão são:

Parâmetro	Valor
Servidor	sync.smartosh.com
Tipo	FTP / FTPS
Utilizador	Fornecido pela consultoria
Senha	Fornecida pela consultoria

Configurar o conector no Smart OSH

1. Aceder ao tenant correspondente com um utilizador Administrador.
2. Ir a Opções → Conexão de dados e adicionar um novo conector com os seguintes valores:

Campo	Valor
Código importação	GENERIC
Tipo	FTP / FTPS (ou SFTP se fornecido pelo cliente)
URL	sync.smartosh.com (ou o servidor do cliente)
Caminho	Deixar em branco salvo indicação do suporte
Utilizador	Fornecido pela consultoria
Senha	Fornecida pela consultoria
Ativo	Sim
Sobrescrever	Sim

3. Guardar a configuração.
4. A importação pode ser forçada a qualquer momento com a ação Sincronizar agora.

Servidor FTP do cliente

Se o cliente fornecer o seu próprio servidor, deve especificar-se o tipo (FTP / FTPS / SFTP) conforme aplicável. Para SFTP é permitido que os ficheiros estejam numa subpasta concreta, indicando-a no campo Caminho.

Conteúdo dos ficheiros

• Em Excel, os separadores devem chamar-se e ordenar-se conforme indica a especificação.
• Em CSV, cada tabela vai num ficheiro, com prefixo numérico para fixar a ordem de carga.
• Em qualquer caso, incluem-se apenas as colunas com dados a transferir. Não é necessário criar todas as colunas de todos os campos.

Especificação detalhada de campos

A lista completa de separadores, nomes de tabelas e campos disponíveis está publicada em smart.smartosh.com/kb020 (requer autenticação).

Anexo: erros controlados

Durante o processamento, o conector pode emitir os seguintes erros:

Mensagem	Explicação
El formato no está correctamente definido y no se dispone de información sobre el mapeo '{0}'	Falta a coluna Operação no Excel.
No hay valor en la columna '{0}' y este es necesario, {1}	Faltam campos obrigatórios ou estão vazios.
Se ha encontrado más de un registro a actualizar basándose en el identificador. La operación no puede continuar.	Os registos identificados por código devem ser únicos.
No existe la {1} con Código {0} ni tampoco en los códigos equivalentes...	Erro de dados: não é possível determinar se inserir ou atualizar.
Error al asignar el valor '{0}' al campo '{1}'	Formato incorreto do valor (depende do campo).
Error al EscribirFTP en la conexión	Problema de conexão ou permissões ao escrever no FTP.

Cuidado

Se uma sincronização terminar com erros, rever sempre o histórico do conector antes de relançar a operação. Forçar Sincronizar agora com dados defeituosos apenas repetirá o erro.

---

Fonte: KB020 «Conector genérico para a sincronização de dados via ficheiros de intercâmbio», módulo Consultoria, versão 1.5, 19-04-2021.