XML para Tabela

• Tipo de Tarefa: xml-to-table

A Tarefa XML para Tabela permite importar dados de um ficheiro XML com estrutura tabular e inseri-los numa tabela de um base de dados. A sua função é dupla: conecta-se a um base de dados para escrever fisicamente os dados e, simultaneamente, expõe os dados importados como um Dataset para utilização por Tarefas subsequentes no Workflow (como um Iterator). Esta Tarefa trabalha com um XML de entrada fornecido por uma Tarefa anterior (ex. "Importar Texto").

1. Conexão com o Base de Dados

Nesta aba, configuram-se todos os parâmetros para estabelecer a ligação ao base de dados de destino.

Tabela de Destino

É possível definir a origem das credenciais para a ligação:

• Manual: permite a inserção manual de todos os dados de ligação e da tabela nos campos abaixo.
• Environment: permite utilizar um ambiente de conexão pré-configurada. Ao selecionar um, os campos de autenticação são preenchidos automaticamente.

Tipo de Base de Dados

Selecione o tipo de base de dados (DBMS) ao qual se pretende ligar. As opções suportadas incluem:

• PostgreSQL
• SQL Server
• MySQL
• Oracle DB (ao usar Oracle, pode escolher entre SID e SERVICE)
• SAP HANA

Ligação SSL

Indique se a ligação ao base de dados deve ocorrer através de um canal seguro.

Autenticação

Campo	Descrição
Host	Endereço do base de dados externo autorizado.
Porta	Porta prevista da ligação ao base de dados externo.
Nome DB	Nome do base de dados ao qual se pretende ligar.
User	Nome de utilizador para aceder ao base de dados.
Definir Password	Abre uma janela para inserir a palavra-passe de forma segura.

Gestão da Tabela

Define como a tarefa deve interagir com a tabela física no base de dados.

1. Tabela de destino: determina a ação a ser executada na tabela:

• Criar tabela: cria sempre uma nova tabela. A operação falha se já existir uma tabela com o mesmo nome.
• Criar tabela se não existir: cria uma nova tabela apenas se não existir já uma tabela com o mesmo nome.
• Tabela existente: insere os dados numa tabela já presente. Por defeito, os novos dados são adicionados aos já existentes (Append). Ao ativar a caixa Truncate Insert, a tabela é esvaziada antes de inserir os novos dados.

2. Nome da tabela de destino: nome da tabela a ser criada ou onde os dados serão escritos (ex. utenti, prodotti, log_eventi).

2. Estrutura Tabular

A aba Estrutura Tabular permite definir os campos (colunas) da tabela e mapear cada coluna com os elementos do ficheiro XML de origem.

Campos Disponíveis

Cada linha representa uma coluna da tabela. Para cada campo é possível configurar:

Campo	Descrição
Tipo	Tipo de dado do campo. Valores disponíveis: NUMERICO, STRINGA, DATA, DATA E ORA
Precisão	Para NUMERICO: número máximo de dígitos; para STRINGA: comprimento máximo
Alias	Nome efetivo da coluna na tabela do base de dados. Será este o nome visível no DB.
Expressão JSONPath	Expressão JSONPath para extrair o valor do ficheiro XML de origem (ex. $.persona.info.name)

Gestão da Estrutura da Tabela

No canto inferior direito da Estrutura Tabular estão presentes três botões:

Botão	Ação
Salvar	Salva a estrutura definida
Importar	Importa uma estrutura existente
Exportar	Exporta a estrutura definida

Esta funcionalidade permite salvar, exportar ou reutilizar mapeamentos, evitando a compilação manual de campos e reduzindo o risco de erros.

Nota Técnica

• Visibilidade: As estruturas salvas no sistema são visíveis apenas para o utilizador que as criou.
• Aprofundamento: Para uma descrição detalhada de todas as opções e da lógica de funcionamento, consulte a página Estrutura da Tabela.

3. Exemplo de Configuração

Para criar uma tabela utenti com os seguintes campos:

Tipo	Alias	Expressão JSONPath
STRINGA	name	$.user.info.name
STRINGA	email	$.user.info.email
NUMERICO	age	$.user.info.age
STRINGA	city	$.address.city
DATA	registration_date	$.registration.date
DATA E HORA	registration_datetime	$.registration.datetime

O resultado desta configuração será a criação de uma tabela no banco de dados com as colunas name, email, age, city, registration_date e registration_datetime (Alias) preenchidas com os valores extraídos do XML (Expressão JSONPath).

Alias com Caracteres Especiais ou Maiúsculas

Se pretender usar letras maiúsculas, caracteres especiais ou espaços nos nomes das colunas, é necessário envolver o Alias em aspas duplas (ex: "Nome de Utilizador").

Tipo	Alias	Expressão JSONPath
STRINGA	“Name”	$.name
STRINGA	“Surname”	$.surname

Resultado no Banco de Dados

4. Gestão de Estruturas XML Aninhadas

O Task XML to Table é capaz de gerir ficheiros XML que contêm elementos aninhados, ou seja, uma hierarquia de dados dentro do registo principal. Em vez de exigir a criação de tabelas separadas (normalização), o Task pode serializar todo o bloco de dados aninhado numa única coluna de texto, tipicamente em formato JSON.

Exemplo Prático

Consideramos o seguinte ficheiro XML de entrada, onde cada <person> tem uma lista aninhada de <departments>:

<people>
 <person>
 <name>Luca</name>
 <surname>Rossi</surname>
 <departments>
 <department>Marketing</department>
 <department>Sales</department>
 </departments>
 </person>
 <person>
 <name>Maria</name>
 <surname>Bianchi</surname>
 <departments>
 <department>HR</department>
 </departments>
 </person>
 ...
</people>

O objetivo é mapear cada <person> para uma coluna da tabela, preservando a lista de departamentos associados a cada pessoa.

Configuração na "Estrutura Tabular"

Para obter este resultado, a configuração na aba "Estrutura Tabular" será a seguinte:

Tipo	Precisão	Alias	Expressão JSONPath
String	1000	name	$.name
String	1000	surname	$.surname
String	4000	departments	$.departments

Explicação:

1. As colunas name e surname são mapeadas de forma direta, pois os seus valores são elementos simples (<name>, <surname>).
2. Para a coluna departments, a Expressão é definida como departments. Isto indica à Tarefa que não deve procurar um único valor, mas sim pegar no conteúdo completo da tag <departments> para cada pessoa.
3. A Tarefa converte automaticamente este fragmento XML no seu equivalente JSON antes de o inserir na coluna do banco de dados.

Resultado no Banco de Dados

Ao aplicar esta configuração, a Tarefa produzirá uma tabela na qual a coluna departments contém uma string JSON que representa a estrutura aninhada original. Isto permite conservar toda a informação hierárquica num único campo de texto, pronto para ser eventualmente analisado por outras ferramentas ou Tarefas.

Extração de sub-elementos com JSONPath

Se, por outro lado, se quisesse extrair elementos aninhados individuais, como por exemplo os nomes dos departamentos, é possível utilizar uma Expressão JSONPath específica. Por exemplo:

Tipo	Precisão	Alias	Expressão JSONPath
String	1000	name	$.name
String	1000	surname	$.surname
String	1000	department_names	$.departments.department[*].details.name

Com esta configuração, a Tarefa XML to Table seleciona todos os valores name presentes no array department e insere-os na coluna department_names do banco de dados, separando-os eventualmente por uma vírgula.

Resultado no Banco de Dados

name	surname	department_names
Luca	Rossi	Marketing, Sales
Maria	Bianchi	HR

Esta abordagem permite extrair apenas os dados necessários, sem serializar todo o bloco JSON, tornando a tabela mais facilmente consultável e utilizável em outras Tarefas ou relatórios.

5. Parâmetros de Saída

Assim que a Tarefa XML to Table concluir o processamento, expõe um rico conjunto de parâmetros de saída. Estes parâmetros não só fornecem informações sobre o resultado da operação, mas também disponibilizam os dados processados em vários formatos para as Tarefas subsequentes.

• result: Fornece o estado geral da execução da Tarefa (ex: "Success" ou uma mensagem de erro).
• targetTable: Retorna o nome da tabela do banco de dados onde os dados foram inseridos.
• rowCount: Indica o número total de linhas que foram inseridas na tabela de destino.
• DataExportCsv: Retorna o conjunto completo de dados processados, formatado como texto em formato CSV (Comma-Separated Values).
• DataExportJson: Retorna o conjunto completo de dados processados, formatado como uma string JSON.
• Dataset: Este parâmetro representa o nome da coluna da tabela (Ex: name). É o parâmetro mais importante para ligar esta Tarefa a um Iterador. Para aceder aos valores de uma coluna específica durante uma iteração, utiliza-se a sintaxe Dataset.NomeColuna.
• DataColumn: Este parâmetro permite aceder a todo o conteúdo de uma coluna como uma única entidade (por exemplo, um array ou uma lista).
• DataColumn.NomeColuna: Retorna todos os valores da coluna “NomeColuna”. Ex: “Luca, Maria, Giovanni, Elena”
• resultJson: representa o resultado da execução da tarefa em formato JSON, incluindo informações gerais, configurações e detalhes da execução.

6. Exemplo de parâmetro resultJson

{
  "run_info": {
    "status": "Completed",
    "run_result": "Success"
  },
  "output_parameters": {
    "exitStatus": "0"
  }
}