A Fonte de Dados é um recurso disponível no lado servidor dos projetos Cronapp e possibilita a comunicação bidirecional entre uma origem de dados, como um banco de dados, e diversas ferramentas no Cronapp, como páginas ou relatórios. Essa comunicação é realizada através do protocolo OData e possui diversos recursos como filtros, tratamento de dados, eventos, tratamento de segurança, geração de recurso REST e a possibilidade de reutilização da mesma Fonte de Dados em várias ferramentas do Cronapp. Esses aspectos garantem a interoperabilidade e integração entre as diferentes camadas do sistema.

Open

Tipos de Fontes de dados

O Cronapp possui algumas variações (tipos) de Fonte de dados, essas variações fazem referências a origem dos dados e a possibilidade de personalização dos dados obtidos. 

Open

Personalizável

Para utilizar um dos tipos abaixo, primeiro será necessário criar e configurar uma Fonte de dados.

• Bloco de Programação (servidor): configure um bloco de programação servidor para retornar uma lista de objetos.

• Consulta a Entidades: selecione uma classe do sistema e faça filtros a partir de uma consulta JPQL com o Assistente de consulta.

• SQL Nativo: selecione um diagrama de dados (namespace) do sistema e faça filtros a partir de consultas SQL nativa, utilizando o Assistente de consulta ou declarações SQL.

• Web Services: utilize um endpoint REST ou um endereço SOAP (*.wsdl).

Não personalizável

Para utilizar o tipo abaixo, basta selecioná-la a partir de alguma ferramenta como Editor de view ou Relatório.

• Entidade: retornará todos os registros de uma entidade, sem a possibilidade de realizar filtros ou personalização no lado servidor, apenas na requisição do lado cliente. Veja mais detalhes no tópico "Filtros e Parâmetros" da documentação Componente visual fonte de dados.

Acesso à lista

É possível acessar a lista das Fontes de dados do projeto a partir da árvore de recursos, no diretório Fontes de Dados (Localização: /Fontes de Dados/) (destaque 2 na árvore de recursos), ou através da janela Buscar Fonte de Dados. Para abrir a janela, acesse no menu do sistema: Projeto > Fonte de dados. 

O diretório Fontes de Dados (destaque 2 na árvore de recursos) permite criar subdiretórios para organizar as Fontes de dados do sistema (3). Ao abrir a janela Buscar Fonte de Dados, a lista estará agrupada pelo tipo da Fonte de dados (Bloco de programação, Consulta a Entidades, SQL Nativo ou Web Services) e por diretório (3).

Open

1. Janela Buscar Fonte de Dados: lista as Fontes de dados do projeto e permite criar, editar, duplicar ou excluir. 

2. Diretório Fontes de Dados: exibe a lista das Fontes de dados do sistema.

   • A árvore de recurso lista as Fontes de dados de forma hierárquica, exibindo diretórios e subdiretórios.

   • A janela de seleção exibe as Fontes de dados de forma agrupada, separando pelo tipo Fonte de dados (Bloco de programação, Consulta a Entidades, SQL Nativo ou Web Services) e depois por diretórios.

3. Subdiretório: utilize subdiretórios para organizar as Fontes de dados de acordo as necessidades do projeto.

4. Fonte de dados: dê um clique duplo para abrir a janela de configuração da Fonte de dados.

   • A árvore de recurso mostra a Fonte de dados com o ícone do seu tipo e nome.

   • A janela de seleção mostra o nome e permite expandir a Fonte de dados para exibir mais informações (5).

5. Informações: ao expandir a Fonte de dados na janela, é possível visualizar o que alimenta a fonte de dados, filtros e informações de erros na configuração da Fonte de dados. 

6. Erro: quando uma Fonte de dados possui algum erro de configuração, um ícone de alerta é exibido. Posicione o cursor do mouse sobre o ícone para exibir um tooltip com informações do problema.

7. Editar: abre a janela de edição da Fonte de dados.

8. Excluir: apaga a Fonte de dados selecionada.

9. Duplicar: faz uma cópia da Fonte de dados selecionada.

10. Opções/Ações: abre um menu com opções para gerar recursos a partir da Fonte de dados. Essas opções também estão disponíveis no item "Ações" no menu de contexto da Fonte de dados, veja mais detalhes no tópico Drag and Drop a ações da Fonte de dados.

11. Botão Nova Fonte de dados: abre a janela para configurar uma nova Fonte de dados.

12. Botão Selecionar: abre a janela de configuração da Fonte de dados selecionada.

Criar e Configurar

É possível criar uma Fonte de dados por vários caminhos:

1. Na estrutura de arquivos, posicione o mouse sobre o diretório Fontes de Dados (destaque 2 da figura 3) (Localização: /Fontes de Dados/), clique no ícone (+) ao lado e selecione Fonte de dados.

2. Na estrutura de arquivos, abra o menu de contexto do diretório Fontes de Dados (destaque 2 da figura 3) (Localização: /Fontes de Dados/) e acesse Novo > Fonte de dados.

3. Na janela Buscar Fonte de Dados, clique no botão Nova Fonte de dados (10 da figura 3).

4. Nas ferramentas que utilizam a Fonte de dados, como Editor de views ou Dashboard, ao abrir a janela de seleção da Fonte de dados, é possível encontrar o botão Nova Fonte de dados.

A janela de edição possui diversos recursos para personalizar a Fonte de dados. A configuração mais básica necessita apenas dos campos: Nome da consulta (destaque 6 da Figura 4), Tipo da Fonte de dados (7) e Origem dos dados (8).

Open

1. Identificador: identificador único da Fonte de dados no projeto, gerado automaticamente pela aplicação Cronapp. Este campo não pode ser editado. 

   • A Fonte de dados sempre é criada com um identificador padrão único e imutável (ex.: "query123456"), ao inserir um valor no campo "Alias" (2), um segundo identificador é criado e a Fonte de dados passará a atender ambas requisições, isso possibilita gerar endereços REST (3) personalizados. Internamente, o Cronapp sempre utilizará o identificador padrão.

2. Alias: campo opcional que permite criar um identificador personalizado para tornar a URI mais amigável. Não são permitidos espaços ou caracteres especiais.

3. Endereço REST: independentemente do tipo da Fonte de dados, ela sempre irá gerar um endereço REST (URN). Esse recurso atenderá aos principais verbos HTTP (aba Ações) e pode ser utilizado dentro do projeto ou fora, com um token de autenticação (X-AUTH-TOKEN) ou habilitando as permissões da Fonte de dados e seus atributos (abas Ações e Campos).

   • Se o campo "Alias" for preenchido, o endereço REST gerado com base nesse "Alias" funcionará enquanto ele estiver configurado na Fonte de Dados. Se o "Alias" for removido, o endereço deixará de funcionar. Caso o "Alias" não seja preenchido (configuração padrão ao criar a Fonte de Dados), o endereço usará o identificador nativo.

4. Copiar URL: copia o URN da Fonte de dados.

5. Sinalização de Erro: ao detectar erro de configuração, um ícone de alerta é exibido. Posicione o cursor do mouse sobre o ícone para exibir um tooltip com informações do problema.

6. Nome da consulta: nome amigável da consulta exibido na janela de seleção das Fontes de dados, aceita espaços e alguns caracteres especiais.

7. Tipo da fonte: define o tipo da Origem dos dados (8), podendo ser Entidade (classe do namespace), SQL Nativo (consulta ao Banco de dados), Bloco de programação (função Java) ou Web services (REST ou SOAP).

8. Origem dos dados: o campo sempre exibirá o que foi selecionado, já os botões, vão variar a depender do que for escolhido no campo "Tipo da fonte" (7).

   • Consulta a Entidades: exibe um botão para selecionar uma das classes de qualquer Diagrama de dados (namespace) do projeto.

   • Bloco de programação: exibirá botões para selecionar uma das funções de bloco servidor ou criar um novo bloco de programação. A função deve retornar uma lista de objeto JSON.

   • Web Service: abre uma janela que permite configurar um endereço REST ou SOAP. Veja mais detalhes em Fonte de dados tipo Web Service (REST / SOAP).

   • SQL Nativo: permite selecionar um dos namespaces (Diagrama de dados) do projeto.

9. Entidade base: esse campo só é habilitado para as Fontes do tipo Bloco de programação ou web service e é usado para definir os campos do objeto com base em uma das classes do Diagrama de dados (namespace).

10. Opções: conjunto de caixas de seleção, acesse a documentação oficial de cada uma para mais detalhes. 

    • Auditoria em Log: habilita o sistema de auditoria para essa Fonte de dados.

    • Exportar biblioteca: inclui a Fonte de dados selecionada como um recurso ao exportar uma biblioteca do Cronapp.

    • Swagger/Open API: inclui o endpoint gerado pela Fonte de dados selecionada na lista de recursos expostos no Swagger/Open API.

11. Aba Filtro: define uma consulta JPQL ou SQL e permite tratar os filtros e parâmetros criados nas configurações da Fonte de dados.

12. Aba Ações: define permissões para os verbos HTTP.

13. Aba Eventos: chama ações em diversos momentos da execução da Fonte de dados.

14. Aba Campos: configura os atributos (campos) dos objetos e dá permissões diferenciadas a partir dos permissionáveis.

15. Aba Campos calculados: adiciona novos campos ao mapa da Fonte de dados.

16. Aba Cabeçalhos: adiciona cabeçalho em Fonte de dados via Web Services.

17. Aba Tratamento de erros: adiciona mensagens de erros personalizadas, permite internacionalização dessas mensagens.

Aba Filtro

Essa aba permite definir as consultas JPQL e SQL para as Fontes de dados Consulta a Entidades e SQL Nativo, respectivamente. Já os filtros/parâmetros (destaque 3 da figura 4.1) possuem diferenças a depender do tipo de Fonte de dados:

• Consulta a Entidades: os filtros são gerados a partir da cláusula where da consulta JPQL (destaque 1 da figura 4.1) ou ao utilizar a expressão ":<parâmetro>" (dois pontos + nome do parâmetro) em outras partes da consulta.

• Bloco de programação: os filtros são criados a partir dos parâmetros da função de bloco de programação vinculada.

• Web Services:

  • REST: os filtros são definidos através das configurações dos parâmetros na aba Ações. Cada verbo da aba Ações (Para obter, Para inserir...) permite configurar novos parâmetros e escolher como serão alimentados, caso escolha a opção "Parâmetro" na coluna Valor do campo e informe um nome, esse parâmetro será exibido na lista de parâmetros da aba Filtro (3). Veja mais detalhes da configuração de parâmetros no tópico Parâmetros e Constantes.
    Também é possível definir um parâmetro no endPoint do recurso e gerar rotas diferentes com base em algum atributo. Ao utilizar a expressão ":<parâmetro>" (dois pontos + nome do parâmetro) no endereço do endPoint (ex: http://www.ws.com/usuario/:idusuario/dados), um filtro ("idusuario") será criado na lista de parâmetros da aba Filtro (3).

  • SOAP: os filtros são definidos através dos parâmetros dos métodos selecionados na aba Ações. Cada verbo dessa aba (Para obter, Para inserir...) permite selecionar um dos métodos presentes no recurso SOAP, caso o método escolhido possua parâmetro e na configuração desse parâmetro seja escolhido a opção "Parâmetro" na coluna Valor do campo e definido um nome, esse nome será exibido na lista de parâmetros da aba Filtro (3). Veja mais detalhes da configuração de parâmetros no tópico Parâmetros e Constantes.

• SQL Nativo: os filtros são gerados a partir da cláusula where da consulta SQL (destaque 1 da figura 4.1) ou ao utilizar a expressão ":<parâmetro>" (dois pontos + nome do parâmetro) em outras partes da consulta.

No exemplo da Figura 4.1, a Fonte de dados retornará todos os usuários que possuem e-mails com algum valor definido no Valor do parâmetro (4), obtido a partir da função "ServidorEmail" do bloco de programação.

Open

1. Consulta: exibe a consulta JPQL ou SQL, esse campo estará desabilitado para as Fontes de dados Bloco de programação e Web Service.

2. Editar: abre a janela do Assistente JPQL e SQL, esse botão estará desabilitado em Fontes de dados Bloco de programação e Web Service.

3. Nome do parâmetro: nome do filtro/parâmetro.

4. Valor do Parâmetro: define um valor estático ou dinâmico para o filtro. Acesse o tópico Parâmetros e Constantes para mais detalhes sobre valores dinâmicos.

5. "…": seleciona uma função de bloco de programação servidor para alimentar o filtro.

6. Novo bloco: cria função de bloco de programação servidor para alimentar o filtro.

7. Limpar: apaga a configuração do filtro.

Aba Ações

Na aba Ações é possível definir o que será executado dos verbos HTTP (get, post, put, delete) e das ações filtrar e contar, além dos permissionáveis que terão acesso. A forma como a ação será executada vai depender do tipo da Fonte de dados.

Open

1. Coluna Ações: nome da ação com um checkbox para ativar ou desativar cada ação (verbos HTTP).

2. Coluna opção da ação: essa coluna terá um nome e um comportamento diferente a depender do tipo da Fonte de dados:

   • Consulta a Entidades: (coluna desabilitada) possui um padrão próprio para executar os verbos e não é possível personalizá-los.

   • Bloco de Programação: ("Método do bloco a utilizar") permite selecionar funções existentes no arquivo do bloco de programação (blockly) que alimenta a Fonte de dados, essas funções podem ser selecionadas para substituir a execução padrão de cada ação. 
     Com exceção das ações "Para Obter" e "Para Contar", as demais ações não permitem configurar o que será passado via parâmetro para as funções selecionadas, a lógica das funções devem se adaptar a esse formato:

     • Para Obter: essa ação é a que alimenta a Fonte de dados e é a única que permite tratar os parâmetros, ao selecionar uma função com parâmetros, esses devem ser configurados na aba Filtro.
       Essa função também será responsável por tratar ordenação e paginação, para isso, utilize o bloco Obter parâmetro da query string para obter os parâmetros de query String da Fonte de dados (ex.: "$orderby"). A função deve retornar uma lista de objetos.

     • Para Inserir: enviará por parâmetro um objeto JSON contendo todos os atributos, inclusive o ID.

     • Para Atualizar: enviará por parâmetro um objeto JSON contendo todos os atributos.

     • Para Remover: enviará por parâmetro um objeto JSON contendo apenas o atributo ID (ex.: {"id":"123456"}).

     • Para Filtrar: ação executada ao utilizar o campo de pesquisa da página CRUD ou os campos de filtro nas colunas da Grade. Utilize o bloco Obter parâmetro da query string para obter os parâmetros de query String da Fonte de dados (ex.: "$filter"). A função deve retornar uma lista de objetos.

     • Para Contar: essa ação é usada internamente para paginar os registros retornados e deve possuir as mesmas configurações da ação "Para Obter".

   • Web Services: 

     • REST: ("Função") é possível definir um endpoint específico para cada ação e adicionar novos parâmetros para essa requisição (ver mais detalhes no tópico "Aba Ações" da documentação Fonte de dados tipo Web Service).

     • SOAP: ("Caminho") é possível selecionar qualquer um dos métodos do serviço SOAP e definir os parâmetros desse método (ver mais detalhes no tópico "Aba Ações" da documentação Fonte de dados tipo Web Service).

   • SQL Nativo: (coluna desabilitada) possui um padrão próprio para executar os verbos e não é possível personalizá-los.

3. "…": esse botão ficará habilitado apenas em Fontes de dados do tipo Web Services e abre uma janela para personalizar os parâmetros do método SOAP ou endpoint REST em cada ação (ver mais detalhes no tópico "Aba Ações" da documentação Fonte de dados tipo Web Service).

4. Permissão: define quais permissionáveis podem executar a ação configurada.

Aba Eventos

A aba Eventos permite rodar alguma função antes ou após a Fonte de dados executar uma ação. Os eventos "Antes" costumam ser muito úteis, pois, caso uma validação não seja atendida, uma exceção pode ser lançada. 

Open

Colunas

1. Eventos: lista de eventos.

2. Campo: exibe a função de bloco de programação selecionada.

3. "…": abre a janela para seleção da função.

4. Novo bloco: cria função de bloco de programação servidor para alimentar o evento.

5. Limpar: exclui os dados do campo.

Eventos

• Antes de Inserir: realiza o evento antes de inserir algum registro.

• Depois de Inserir: realiza o evento após inserir algum registro.

• Antes de Deletar: realiza o evento antes de deletar algum registro.

• Depois de Deletar: realiza o evento após deletar algum registro.

• Antes de Atualizar: realiza o evento antes de atualizar algum registro.

• Depois de Atualizar: realiza o evento após atualizar algum registro.

• Ao navegar: executa a ação ao abrir e ao navegar entre os elementos da Fonte de dados.

• Ao Autorizar: faz uma validação, se o evento lançar uma exceção, ele será bloqueado e o erro será exibido. Isso evitará, por exemplo, que um usuário possa pegar o id para montar e acessar uma requisição sem permissão. O evento será executado para todas as chamadas GET, PUT, DELETE, POST da Fonte de dados. Esse evento costuma ser muito útil em sistemas multitenant. 

• Ao Gerar Erro: tratamento de erros de qualquer natureza durante o processo de manipulação de dados de uma Fonte de Dados.

Aba Campos

A aba Campos é responsável por mapear os objetos manipulados pela Fonte de dados, permitindo configurar cada atributo individualmente. Algumas características dessa aba mudam a depender do tipo de Fonte de dados:

• Consulta a Entidades: apenas o tipo Consulta a Entidades não permite adicionar ou remover campos, pois, como é baseada em classes, exibirá todos os atributos contidos na classe selecionada. Pelo mesmo motivo não estão disponíveis ou habilitados os campos de configuração 6, 7, 8, 10 e 13 da Figura 4.4, já que essas características foram definidas nas classes do Diagrama de dados.

• Bloco de programação: é possível selecionar uma classe no campo "Entidade base" (destaque 8 da figura 4) para preencher todos os seus campos automaticamente. O campo de configuração 10 da figura 4.4 não estará habilitado.

• Web Services: após vincular um endpoint à Fonte de dados, todos os campos do objeto da API serão automaticamente incluídos nessa aba. No entanto, é possível selecionar uma classe no campo "Entidade base" (destaque 8 da figura 4) e substituir todos os atributos pelos da classe selecionada. Isso pode ser útil caso o objeto da API não represente a classe do projeto, utilize a opção "Caminho" (destaque 10 da figura 4.4) para informar o JSON Path de cada atributo do objeto da API.

• SQL Nativo: após definir a consulta SQL na aba Filtro, todos os campos da cláusula select serão automaticamente incluídos, mas também é possível selecionar uma classe no campo "Entidade base" (destaque 8 da figura 4) para adicionar todos os seus atributos automaticamente.

Open

1. Campo a adicionar: nome do novo atributo.

2. Adicionar campo: insere o atributo informado (1).

3. Nome dos campos: coluna com o nome dos atributos.

4. Valor do campo: define um valor estático ou dinâmico para alimentar o atributo. Acesse o tópico Parâmetros e Constantes para mais detalhes das configurações dos valores dinâmicos (Expressão).

5. Tipo do campo: define o tipo do atributo.

   • Web Service: além dos tipos comuns as demais Fontes de dados, possuem os tipos Array e Object, possibilitando obter objetos complexos de uma API, como um array. Para mais detalhes, consulte o tópico correspondente na documentação Fonte de dados tipo Web Service (REST / SOAP). 

6. Permite nulo: define se o campo aceitará valores nulos.

7. Chave: define se o campo é uma das chaves primárias da entidade.

8. "...": selecione uma função bloco de programação servidor existente para alimentar o campo. Para passar um atributo pelo parâmetro da função, utilize a expressão data.<nome_atributo> ou data para enviar o objeto completo.

9. Bloco: cria uma função de bloco de programação para alimentar o campo. 

10. Caminho: disponível apenas para Fontes de dados do tipo Web Services e SQL Nativo.

    • Web Service: permite informa o caminho (JSON Path) do atributo que irá alimentar o campo (ex,: $.data[0].id).

    • SQL Nativo: permite acessar as expressões usadas nos campos, como subqueries ou "CASE WHEN", caso o campo não possua expressão, exibirá apenas o nome do campo no formato: <tabela ou alias>.<nome_campo>. (Veja mais detalhes na documentação Fonte de dados tipo SQL Nativo)

11. Permissões: define restrições para cada verbo aos permissionáveis cadastrados no sistema.

     

12. Limpar: apaga as configurações feitas no atributo.

13. Excluir: exclui o atributo.

Aba Campos calculados

A aba Campos calculados permite incluir campos temporários nos objetos manipulados pela Fonte de dados. Diferentemente da aba Campos, aqui os atributos e seus valores não são persistidos, existem apenas durante o tempo de execução, na memória na aplicação.

Os campos calculados não suportam filtros, pois as requisições de filtros são encaminhadas ao banco de dados ou a outro recurso que alimenta a Fonte de dados e lá, os campos calculados não existem. 

Exemplo de uso: Em uma Fonte de dados vinculada a entidade usuários, podemos criar um campo calculado idadeAtual, ela chamará uma função Servidor que obtém o campo dataNascimento do usuário e retornará a sua idade baseado na data atual. Dessa forma, sempre que precisar exibir a idade atual dos usuários, basta chamar o campo calculado idadeAtual da Fonte de dados.

Open

1. Campo a adicionar: nome do novo atributo.

2. Adicionar campo: insere o atributo informado (1).

3. Nome dos campos: coluna com o nome dos campos calculados.

4. Valor do campo: define um valor estático ou dinâmico para alimentar o campo. Acesse o tópico Parâmetros e Constantes para mais detalhes sobre valores dinâmicos (Expressão).

5. Tipo: define o tipo do atributo.

   • Web Service: além dos tipos comuns as demais Fontes de dados, possuem os tipos Array e Object, possibilitando obter e manipular objetos complexo de uma API, como um array. Para mais detalhes, consulte o tópico correspondente na documentação Fonte de dados tipo Web Service (REST / SOAP). 

6. "...": selecione uma função bloco de programação servidor existente para alimentar o campo. Para passar um atributo pelo parâmetro da função, utilize a expressão data.<nome_atributo> ou data para enviar o objeto completo.

7. Bloco: cria uma função de bloco de programação para alimentar o campo.

8. Caminho: opção não disponível para Campos calculados.

9. Permissões: define restrições para cada verbo aos permissionáveis cadastrados no sistema.

10. Limpar: apaga as configurações feitas no atributo.

11. Excluir: exclui o atributo.

Entidades relacionadas

Os campos calculados permitem referenciar atributos da própria entidade ou os atributos de outras entidades que possuam relacionamento 1 para N. Podemos utilizar esse recurso em diversas situações, por exemplo, em um relacionamento entre as entidades Cidade, Estado e País, no qual a Fonte de dados da entidade Cidade pode ter acesso a qualquer atributo das entidades Estado ou País. Na Figura 4.5.1, a Fonte de dados tem acesso ao atributo "região" da entidade Estado e ao atributo "nome" da entidade País. O termo this representa a entidade atual.

Como não existem limites de relacionamentos que podem ser feitos em um banco de dados, o Cronapp limita a lista de atributos (via caixa de seleção) até o terceiro relacionamento. Porém, é possível inserir manualmente relacionamentos maiores - Exemplo: this.estado.pais.continente.planeta.distanciaSolemKm .

Open

Aba Cabeçalhos

Essa aba é utilizada apenas para as Fontes de dados do tipo Web services e permite configurar os cabeçalhos das requisições HTTP do endPoint configurado. Por padrão, os campos Accept e Content-Type já vem definidos ao criar uma Fonte do tipo Web Services, porém é possível alterar e adicionar novos.

Open

1. Campo a adicionar: nome do novo cabeçalho.