Função

A fonte de dados normalmente é utilizada para fazer a comunicação entre os dados persistidos (ex.: banco de dados) e a tela na qual o usuário realiza alguma interação. Ela permite tratar os dados em componentes visuais, relatórios, sistema BPM e gerar requisições REST dentro ou fora da aplicação. A fonte de dados utiliza a tecnologia OData para trafegar os dados e pode ser alimentada por uma consulta JPQL, bloco de programação ou web services (REST e SOAP). Esses fatores garantem a interoperabilidade e integração entre as camadas do sistema.

Tipos

Existem 3 tipos de fonte de dados personalizáveis (Blocos, Entidades e Web services) e 1 não personalizável (Classe):

• Bloco de Programação: configure um bloco de programação servidor para retornar uma lista de objetos.
• Entidades: selecione uma classe do sistema e faça um filtro a partir de uma consulta JPQL.
• Web Services: utilize um endpoint REST ou um endereço *.wsdl SOAP. Para mais detalhes, acesse a documentação Fonte de dados tipo Web Service (REST / SOAP).
• Classe: retornará todos os registros de uma classe sem a possibilidade de configurações ou filtros.

A fonte de dados do tipo Classe só estará disponível ao selecionar uma fonte de dados a partir de um componente visual, relatório ou outras ferramentas. Para utilizá-la, basta selecionar qual Entidade irá alimentar o componente. Já para os demais tipos, é necessário criar e configurar a fonte de dados, apontar para o componente visual fonte de dados e depois vincular ao componente que será alimentado.

Uso

A maioria dos componentes que necessitam de uma fonte de dados possuem uma propriedade Origem dos dados ou Configurações onde é possível selecionar uma fonte de dados já existente ou criar uma nova. 

Na Figura 1.1 temos o ícone do Componente visual Fonte de dados (destaque 1) que alimenta a lista do componente Caixa de seleção múltipla (destaque 2). O ícone de fonte de dados só é exibido no momento de edição da view, caso não queira visualizar esses ícones no momento da edição, basta clicar no botão Exibir elementos não visuais (3) para ocultar ou exibi-lo novamente.

Figura 1.1 - Ícone fonte de dados (1) na tela de edição da view

Nem sempre é necessário arrastar o componente Fonte de dados para a área de edição da view, ao definir uma fonte de dados nas propriedades Origem dos Dados ou Configuração (destaque 1 da figura 1.2) de algum outro componente, o ícone é criado automaticamente acima do componente editado na janela de edição da view (destaque 2 da figura 1.2).

Acesso as propriedades

As propriedades de configuração do componente visual fonte de dados podem ser acessadas através do menu lateral, ao selecionar o componente na área de edição da view - como na Figura 1.1, ou através das janelas de configurações de outros componentes - como mostrado na Figura 1.2.

Figura 1.2 - Acesso as propriedades através da janela de configurações do componente Grade

Principais propriedades

Na tabela abaixo estão descritas as principais propriedades do componente visual.

Aba de Estilos

O componente visual Fonte de dados só é visível em tempo de desenvolvimento, logo não necessita de campos de estilo personalizado.

Filtros e Parâmetros

Com o Filtros e Parâmetros é possível adicionar grupos de regras e agrupá-los com outros grupos usando conectivos lógicos (e / ou). Regras podem ser criadas a partir de expressões, campos da tela, conteúdo estático ou blocos de programação.

Figura 2.1 - Janela de Filtros e Parâmetros

1. Configuração do Grupo: define o condicional entre suas regras e outros grupos; 
2. Campo de seleção de condicional (e / ou) do grupo;
3. Adiciona nova regra a esse grupo;
4. Adiciona novo grupo filho;
5. Exclui grupo (não é possível excluir o primeiro grupo da hierarquia);
6. Configuração da Regra: define um elemento de comparação entre um atributo da fonte de dados e outro elemento;
7. Seleciona o atributo da fonte de dados;
8. Seleciona o operador de comparação (=; ≠; <; >; <= ou >=);
9. Seleciona o tipo do que será comparado: expressão, booleano, String e outros;
10. Campo para informar o que será comparado: expressões, data, String, bloco de programação ou outros;
11. Abre uma nova janela para informar uma expressão, selecionar um bloco de programação ou um campo na tela que será exibido no campo 10;
12. Exclui regra.

Figura 2.2 - Exemplo de uso da propriedade Filtros e Parâmetros

No exemplo da Figura 2.2, a sintaxe de comparação pode ser lida da seguinte forma:

(email = 'pedro.porto@email.com') AND ((name = cronapi.client('js.blockly.BlocoCliente.Funcao').attr().run()) OR (login = 'pedro.porto'))

A expressão cronapi.client('js.blockly.BlocoCliente.Funcao').attr().run() se trata do retorno de uma função de bloco de programação, ao selecionar essa função no botão "..." (destaque 11 da Figura 2.1), o sistema preenche o endereço e a chamada da função.

Ordenação

A ordenação ocorre selecionando um ou mais campos da fonte de dados e definindo a ordem (ascendente ou descendente).

Figura 2.3 - Ordenação do campo 'name' em ordem crescente

1. Adiciona uma nova ordenação;
2. Seleciona o campo da fonte de dados que será o ordenador;
3. Define se a ordenação será ASCendente ou DESCendente.

Mestre Detalhe

A propriedade Mestre detalhe gera uma ligação entre os parâmetros de uma fonte de dados com expressões, campos na tela, bloco de programação ou parâmetros de outra fonte de dados. O mestre detalhe pode ser utilizado para fazer o filtro entre componentes. Por exemplo: uma tela possui 2 caixas de seleção dinâmica, a primeira lista os estados de um país, enquanto a segunda, as cidades. Ao fazer o vínculo Mestre detalhe entre as fontes de dados e selecionar um estado, a caixa de seleção de cidades só exibirá as cidades referente ao estado selecionado. Isso só funcionará em entidades que possuem relacionamento 1 para N.

Figura 2.4 - Ligação entre o atributo id da fonte de dados e o id de outra fonte de dados da view

1. Adiciona uma nova ligação;
2. Seleciona o atributo da fonte de dados principal;
3. Operador de comparação igual (único possível);
4. Seleciona o tipo do que será comparado: expressão, booleano, String e outros;
5. Atributo da fonte filho, que pode ser: expressões, bloco de programação, campo da tela ou outros;
6. Abre uma nova janela para informar uma expressão, selecionar um bloco de programação ou um campo na tela. A seleção será exibida no campo (5);
7. Exclui a ligação.

Origem dos Dados

A propriedade Origem dos Dados abre a janela Lista de Fonte de dados e permite vincular um componente visual Fonte de dados a uma fonte de dados já criada. Também é possível criar uma fonte de dados a partir do botão Nova fonte de dados.

Nessa janela são exibidos os 4 tipos de fontes de dados.

Figura 2.5 - Seleção de uma fonte de dados ou entidade

1. Coluna nome: separa em níveis as fontes de dados por seus tipos (Bloco de programação, Classe, Entidade, Web Services). 
2. Coluna Tipo: informa se o item é uma fonte de dados ou entidade.
3. Coluna 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.
4. Coluna Editar: abre a janela de edição da fonte de dados.
5. Manter compatibilidade com Cronapp 1.0: item destinado a manter a compatibilidade dos projetos criados na versão 1.0 do Cronapp com a versão atual.

Configurações

É possível criar ou editar uma fonte de dados por vários caminhos: através da propriedade Origem dos dados de algum componente que utiliza fontes de dados (Figura 1.2), pelo ícone da Fonte de dados (destaque 1 da figura 3.1) ou ainda, pelo diretório Fontes de dados (Localização: /

) do menu lateral (destaque 2 da figura 3.1).

O menu lateral Fontes de Dados permite criar subdiretórios para organizar as fontes de dados do sistema. Ao abrir janelas que fazem a seleção da fonte de dados (figura 3.1), ocorrerá dois filtros em sequência: o primeiro é o tipo da fonte de dados (Bloco de programação, Entidade, Classe ou Web Services) e o segundo são os diretórios (destaque 3 da figura 3.1).

Figura 3.1 - Acesso as fontes de dados pelo menu do sistema

1. Ícone Fonte de dados: abre a janela "Buscar Fonte de Dados" onde é possível criar, editar ou excluir fontes de dados.
2. Diretório Fontes de Dados: exibe as fontes de dados do sistema.
   • No menu lateral são listadas as fontes de dados. Dê um duplo clique para editar um datasource ou selecione no menu de contexto "Novo > Fonte de Dados" para criar um.
   • Na janela de seleção as fontes de dados são organizadas pelo tipo da fonte de dados (Bloco de programação, Entidade ou Web Services).
3. Diretório: utilizado para agrupar fontes de dados. Se existir duas fontes de dados de tipos diferentes no mesmo diretório, esse diretório aparecerá vinculado aos 2 filtros de tipos.
4. Fonte de dados: 
   • No menu lateral cada fonte de dados terá o ícone do que o alimenta: Bloco de programação, Entidade ou Web services.
   • Na janela de seleção o ícone das fontes de dados será sempre o mesmo.
5. Informações: ao expandir a fonte de dados na janela, é possível visualizar o que alimenta a fonte de dados (nome do bloco ou endereço REST) 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.

• Botão Nova fonte de dados: abre a janela para configurar uma nova fonte de dados (Figura 3.2).

Edição da Fonte de dados

A janela de edição possui diversas configurações para personalizar a fonte de dados. A configuração mais básica necessita apenas dos campos: Nome da consulta (destaque 4 da Figura 3.2), tipo da fonte de dados (5) e Origem (6).

Figura 3.2 - Janela de edição da fonte de dados

1. Identificador: identificador único da fonte de dados no sistema. O trecho de endereço (URN) ao lado é o endereço de requisições REST da fonte de dados, permitindo gerar uma API, garantindo a interoperabilidade entre os módulos do sistema ou fora dele.
2. Copiar URL: copia o URN da fonte de dados.
3. Sinalização de Erro: ao detectar erro nas configurações da fonte de dados, um ícone de alerta é exibido. Posicione o curso do mouse sobre o ícone para exibir um tooltip com informações do problema.
4. Nome da consulta: nome que identifica a consulta para o programador no momento da seleção das fontes de dados.
5. Tipo da fonte: define se a fonte de dados estará vinculada a uma entidade, bloco de programação ou web service.
6. Origem da fonte: seleção de um bloco de programação, entidade ou serviço web (REST ou SOAP):
   • campo: exibe a entidade, bloco de programação ou endpoint (URL Base) selecionado.
   • Botão "…": abre janela de seleção de entidade, bloco de programação ou configuração do serviço web. Ao selecionar a opção "web service" no campo 5, esse botão passa a abrir a janela de seleção de campos do recurso serviço web. Para mais detalhes, acesse o tópico Edição em Web Services.
   • Botão Bloco de programação: abre uma janela para a criação de bloco de programação.
   • Botão Excluir: limpa a seleção do bloco de programação ou entidade.
7. Entidade base: esse campo só é ativo para fontes do tipo Bloco de programação ou web service e é usado para definir o mapa da entidade.
8. Auditoria em Log: habilita o sistema de auditoria para essa fonte de dados. Acesse a documentação Log de Auditoria para mais detalhes.
9. Aba Filtro: define uma consulta JPQL ou parâmetros da função dos blocos de programação.
10. Aba Ações: define permissões para os verbos HTTP.
11. Aba Eventos: chama ações em diversos momentos da execução da fonte de dados.
12. Aba Campos: altera o valor de cada campo e dá permissões diferenciada aos permissionáveis.
13. Aba Campo calculados: adiciona novos campos ao mapa retornado da fonte de dados.
14. Aba Cabeçalhos: adiciona cabeçalho em fonte de dados via Web Services.
15. Aba Tratamento de erros: adiciona mensagens de erros personalizadas, permite internacionalização dessas mensagens.

Edição em Web Services

Ao selecionar a opção "Web Services" em Tipo de fonte (destaque 1 da figura 3.2.1), o campo ao lado ficará editável e espera receber o endPoint do serviço REST ou o endereço do arquivo *.wsdl do serviço SOAP que alimentará a fonte de dados, o botão em seguida mudará seu ícone de "..." para o símbolo de "play" (2), clicando, uma janela será aberta para configurar os campos que a fonte de dados irá receber do serviço.

Figura 3.2.1 - Janela de edição da fonte de dados do tipo Web Services

Filtro

Os dados que alimentam a fonte de dados passarão pelas regras definidas nessa aba e a fonte de dados encaminha somente o conteúdo que passar pelo filtro. A forma como o filtro será configurado irá variar de acordo com o tipo da fonte de dados:

• Entidade: são geradas a partir de consultas JPQL (destaque 1 da figura 3.3) que podem ser criadas através do Assistente de consulta visual (botão 2 da Figura 3.3). As regras (where) da consulta são exibidas na área de parâmetros (3).
• Bloco de programação: o filtro é definido pelos parâmetros do bloco de programação vinculado a fonte de dados, esses parâmetros podem ser configurados logo abaixo (destaque 3 da figura 3.3).
• 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 informar um nome, esse parâmetro será exibido na lista de parâmetros da aba Filtro (destaque 3 da figura 3.3).
• Web Services - SOAP: aqui os filtros são definidos através dos parâmetros dos métodos selecionados na aba Ações. Cada verbo da aba Ações (Para obter, Para inserir, ...) permite selecionar um dos métodos presentes no recurso SOAP, caso o método escolhido possua parâmetros e, nas configurações do verbo, for escolhido a opção "Parâmetro" na coluna Valor do campo e informado um nome, esse parâmetro será exibido na lista de parâmetros da aba Filtro (destaque 3 da figura 3.3).

No exemplo da Figura 3.3, a fonte de dados retornará todos os usuários que possuem e-mails de um servidor específico, obtido no retorno do bloco de programação vinculado ao parâmetro email.

Figura 3.3 - Exemplo de filtro para uma entidade

1. Consulta JPQL: exibe a consulta JPQL criada (habilitado somente quando a fonte está vinculada a uma entidade).
2. Editar: abre uma janela para a criação da consulta JPQL em modo visual (habilitado somente quando a fonte está vinculada a uma entidade).
3. Nome do parâmetro: nome das regras geradas por consulta JPQL, parâmetros do bloco de programação ou parâmetro de ações em Web services.
4. Valor do Parâmetro: define um valor estático ou dinâmico, ao selecionar um bloco de programação. Por exemplo, a obtenção do conteúdo de um campo na tela.
5. "…": seleciona uma função de bloco para ser a fonte desse campo.
6. Novo bloco: cria bloco de programação e uma função.
7. Limpar: apaga a dado informado no campo do parâmetro.

Ações

Na aba Ações é possível definir quais os verbos HTTP (get, post, put, delete), filtrar ou contar serão executados e quais permissionáveis terão acesso a esses recursos. A forma como a ação será executada vai depender do tipo da Fonte de dados.

Fontes de dados do tipo Bloco de programação que possua uma entidade vinculada no campo Entidade base exibirá também a opção "Padrão" nas ações (verbos). Essa opção faz com que as ações que possuam essa opção selecionada executem o verbo da mesma forma como ocorre nas fontes de dados do tipo Entidade. Porém, caso queira personalizar a execução do verbo, basta selecionar uma função de bloco de programação (Figura 3.4).

Figura 3.4 - Configurando a ação Remover para uma fonte de dados do tipo Web service REST

1. Coluna Ações: ativa ou desativa cada um dos verbos HTTP.
2. Coluna opção da ação: essa coluna terá um comportamento diferente a depender do tipo da fonte de dados:
   • Entidade: possui um padrão próprio para executar os verbos e não é possível personalizá-los.
   • Bloco de Programação: é possível selecionar apenas funções existentes no arquivo do bloco de programação (blockly) que alimenta a fonte de dados. Essas funções devem receber por parâmetro o objeto da entidade.
   • Web Services (Rest): é possível definir um endpoint específico para cada ação e adicionar novos parâmetros para essa requisição (ver mais em Ações em Web Services).
   • Web Services (SOAP): é possível selecionar qualquer um dos métodos do serviço SOAP e definir os parâmetros desse método (ver mais em Ações em Web Services).
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.
4. Permissão: define quais permissionáveis podem executar esses verbos.

Ações em Web Services

Fontes de dados tipo Web Services permitem configurar os argumentos que serão passados como parâmetros para os métodos do SOAP ou para o endPoint das requisições REST. Essa configuração é feita na janela Obter campos do serviço e pode ser aberta a partir do botão "..." de cada ação (destaque 1 da figura 3.4.1).

Figura 3.4.1 - Configurando ação ações para uma fonte de dados web service REST

1. "...": abre a janela "Obter campos do serviço" para personalizar os parâmetros do método SOAP ou endpoint REST em cada ação.
2. Campo Parâmetro: (só disponível em Web Service REST) nome do novo parâmetro a ser passado na requisição.
3. "+": (só disponível em Web Service REST) inclui o novo parâmetro na lista de queryStrings.
4. Coluna Nome: lista de parâmetros.
5. Coluna Valor do campo: define como será o valor a ser passado, podendo ser tipos estáticos (texto, numérico, data e hora, hora ou lógico), Bloco de programação, Parâmetro ou Expressões. Veja mais detalhes do tópico Parâmetros e constantes.
6. Remover: (só disponível em Web Service REST) remove o parâmetro selecionado.
7. Parâmetros estáticos REST: apenas fontes de dados Web Services REST exibem por padrão os campos URL e Caminho.
   • URL: substitui ou personaliza o endPoint da URL Base:
     • Campo vazio: a requisição será feita a partir de "<URL BASE>/" (nas ações Para Obter e Para Inserir) ou "<URL Base>/{id}" (demais ações)
       • Exemplo
         URL Base: https://www.ws.com.br/user
         URL: <vazio>
         Resultado: https://www.ws.com.br/user
     • Valor relativo: alguns serviços REST geram recursos a partir de um endPoint dentro da URL Base, dessa forma, é possível informar apenas o endereço final (ex.: insert/) para a requisição ser montada a partir da concatenação da URL BASE e o endereço final (ex.: "<URL Base>/list/"). Podemos configurar de 2 formas: Se o primeiro caractere do campo URL não for uma "/" (barra), será concatenado a URL Base com o conteúdo do campo URL, já se o primeiro caractere do campo URL for uma "/" (barra), será concatenado somente o domínio da URL Base com o campo URL. Veja os 2 exemplos a seguir.
       • Situação 1 - Campo URL com o caractere "/"
         URL Base: https://www.ws.com.br/user/
         URL: /insert
         Requisição: https://www.ws.com.br/insert
       • Situação 2 - Campo URL sem o caractere "/"
         URL Base: https://www.ws.com.br/user/
         URL: insert
         Requisição: https://www.ws.com.br/user/insert
     • Valor absoluto: é possível informar um endPoint completo e ignorar totalmente a URL Base.
       • Exemplo
         URL Base: https://www.ws.com.br/user
         URL: https://www.meuoutrowebservicesrest.io/list
         Requisição: https://www.meuoutrowebservicesrest.io/list
   • Caminho: o campo espera receber um JSON Path e é usado para informar qual parte do JSON recebido será aproveitado (ex.: $.data - tudo que estiver dentro do atributo data no JSON). Caso não seja preenchido, será obtido todo o conteúdo do corpo da requisição.
8. Parâmetros:
   • SOAP: serão exibidos os parâmetros dos métodos SOAP selecionado para a ação.
   • REST: devem ser adicionados e configurados os parâmetros queryString.
9. Parâmetro compartilhado: nos casos em que várias ações utilizam o mesmo parâmetro, é possível selecionar a opção "Parâmetro" na coluna Valor do campo (5) e informar um nome ao lado (10). Esse parâmetro passará a ser configurável a partir da aba Filtro e todas as outras ações poderão receber o mesmo valor após selecionar a opção "Parâmetro" e informar o nome.
10. Nome do parâmetro compartilhado: o nome informado na coluna conteúdo (destaque 10 da Figura 3.4.1) será exibido exibido nas configurações da aba Filtro (destaque 1 da Figura 3.4.2).

Figura 3.4.2 - QueryString definidas como parâmetros serão configuradas na aba Filtro

A partir das configurações feitas nas figuras 3.4.1 e 3.4.2, a ação Para Remover terá a seguinte sintaxe.

• id_user: o valor foi obtido a partir do retorno de um bloco de programação (ex.: 123).
• token: o valor foi obtido a partir da constante chave do token (token.{key}) do usuário (ex: ABC321).

DELETE https://607f375302a23c0017e8cec5.mockapi.io/user?id_user=123&token=ABC321

Parâmetros REST

Existem 2 formas de passar parâmetros em requisições REST (via Query String e/ou Rotas) e cada API define como irá tratá-las.

Query String

No formato Questy Stirng, após o endereço do endPoint é adicionado o caractere ? (interrogação) para informar onde começam as declarações dos parâmetros (Chave=Valor) e entre cada parâmetro (Chave=Valor ) é adicionado o caractere & (ampersand),

O endereço abaixo retorna o comentário que possui o id 17 da postagem com o identificador (postId) 4. A configuração na fonte de dados pode ser vista na figura 3.5.2.

https://meusistema.com.br/comentarios/list?postId=4&id=17

Figura 3.4.3 - Adicionando parâmetros queryString a uma requisição REST

Rotas

No formato de rotas, os valores dos parâmetros são passados no meio do endereço, separado pelo caractere / (barra). Algumas APIs utilizam os parâmetros de rotas e queryString juntos.

O endereço abaixo retorna o comentário que possui o id 17 da postagem com o identificador 4. O identificador do post é passado na rota, entre o "...post/" e "/comentários".

https://meusistema.com.br/post/4/comentarios?id=17

Para inserir um parâmetro dinâmico na roda, podemos inserir o caractere :<parâmetro> (dois pontos + nome do parâmetro) nos campos de endereços (URL Base ou campo URL nas configurações da ação) e configurar seu valor na aba Filtro. No exemplo abaixo foi inserido o nome do parâmetro dentro do endereço da URL Base ".../:idPost/..." (destaque 1 da figura 3.4.4), ao reconhecer o caractere ":", o Cronapp cria um campo de parâmetro para na aba Filtro para permitir sua configuração (destaque 2 da figura 3.4.4). Neste exemplo, o parâmetro idPost é alimentado pelo retorno da função de bloco de programação ObterIdPost.

Figura 3.4.4 - Parâmetro criado a partir do endereço com o uso do caractere : (dois pontos)

A quesryString é tratada diretamente nas configurações (janela Obter campos do serviço) da Ação, após criar um parâmetro e informa de onde será obtido o seu valor.

Figura 3.4.5 - Requisição REST que obtém parâmetros REST por Rotas e queryString

Eventos

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

Existem diferenças entre os eventos da fonte de dados (servidor, Figura 3.5) e os eventos do componente visual fonte de dados (cliente). Para mais detalhes de como configurar os eventos, acesse o tópico Lançar exceção ou o tutorial Validação da fonte de dados usando Eventos.

Figura 3.5 - Seleção de uma fonte de dados ou entidade

Colunas

1. Eventos: lista de eventos.
2. Campo: exibe as funções de bloco selecionadas.
3. "…": abre a janela para seleção da função.
4. Criar bloco: cria novo bloco de programação com uma função.
5. Limpar: exclui os dados do campo.

Eventos

• Antes de Inserir:  realiza o evento antes da inserir de algum dado.
• Depois de Inserir: realiza o evento após a inserir de algum dado.
• Antes de Deletar: realiza o evento antes de deletar algum dado.
• Depois de Deletar: realiza o evento após deletar algum dado.
• Antes de Atualizar: realiza o evento antes da atualizar de algum dado.
• Depois de Atualizar: realiza o evento após a atualizar de algum dado.
• Ao navegar: executa a ação ao abrir e ao navegar entre os elementos da fonte.
• Ao Gerar Erro: tratamento de erros de qualquer natureza durante o processo de manipulação de dados de uma Fonte de Dados.

Campos

A aba Campos exibe todos os atributos (campos) da entidade base selecionada, adiciona novos campos ao mapa retornado e trata cada campo de forma individual, definindo valores estáticos ou dinâmicos. 

Não é possível adicionar novos campos para fontes de dados do tipo Entidade, também não são exibidas as configurações de banco de dados (colunas (6), (7) e (8) da Figura 3.6.). Esses recursos só estão disponíveis para as fontes de dados dos tipos Blocos de programação e Web Services.

Figura 3.6 - Aba campos e as várias configurações de seus atributos

1. Campo a adicionar: nome do campo a ser adicionado. Esse campo não é exibido em fontes de dados do tipo Entidade.
2. Adicionar campo: insere um campo a mais em relação aos da entidade base. Esse botão não é exibido em fontes de dados do tipo Entidade.
3. Nome dos campos: coluna com o nome dos campos.
4. Valor do campo: define o tipo do valor que irá alimentar o campo, podendo ser tipos estáticos (Tipos primitivos), Bloco de programação ou Expressões. Acesse o tópico Parâmetros e constantes para mais detalhes.
5. Conteúdo: permite alimentar o campo utilizando outros recursos. Acesse o tópico Parâmetros e constantes para mais detalhes.
6. Tipo do campo: define o tipo do campo.
7. Permite nulo: define se o campo aceitará valores nulos.
8. Chave: define se o campo é uma das chaves primárias da entidade.
9. Bloco: crie ou selecione 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, permite informa o caminho (JSON Path) do atributo que irá alimentar o campo (ex,: $.data[0].id). 
11. Permissões: define restrições aos permissionáveis cadastrados no sistema.
12. Limpar: apaga as configurações feitas no campo.
13. Excluir: exclui o campo.

Campo calculados

Adiciona novos campos temporários às entidades da fonte de dados. Diferentemente da aba Campos, aqui os atributos e seus valores não são persistidos, existem apenas para uso temporário na aplicação.

Exemplo de uso: Em uma fonte de dados vinculada a entidade usuários, podemos criar um campo calculado idade, ela chamará uma função Servidor que obtém o campo data de nascimento 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 idade da fonte de dados.

Figura 3.7 - Aba de campos calculados

1. Campo a adicionar: nome do campo a ser adicionado.
2. Adicionar campo: insere o campo calculado.
3. Nome dos campos: coluna com o nome dos campos.
4. Valor do campo: define o tipo do valor que irá alimentar o campo, podendo ser tipos estáticos (Tipos primitivos) ou Expressões. Acesse o tópico Parâmetros e constantes para mais detalhes.
5. Conteúdo: permite alimentar o campo utilizando outros recursos. Acesse o tópico Parâmetros e constantes para mais detalhes.
6. Tipo do campo: define o tipo do campo.
7. Bloco: crie ou selecione 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 aos permissionáveis cadastrados no sistema.
10. Limpar: apaga as configurações feitas no campo.
11. Excluir: exclui o campo.

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 com a entidade Cidade pode ter acesso a qualquer atributo da entidade Estado ou País. Na Figura 3.8, 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.distanciaSol .

Figura 3.8 - Campos calculados referenciando atributos de outras entidades relacionadas

Cabeçalhos

Permite configurar os cabeçalhos das requisições HTTP. Por padrão, os campos Accept e Content-Type já vem definidos em fontes de dados do tipo Web Services, porém é possível alterá-los e adicionar novos.

Figura 3.9 - Aba Cabeçalhos de uma fonte de dados Web Services

1. Campo a adicionar: nome do cabeçalho a ser adicionado.
2. Adicionar campo: insere o novo cabeçalho.
3. Nome dos cabeçalhos: coluna com o nome dos cabeçalhos.
4. Valor do campo: define o tipo do valor que irá alimentar o cabeçalho, podendo ser tipos fixo (Tipos primitivos) ou Expressões. Acesse o tópico Parâmetros e constantes para mais detalhes.
5. Conteúdo: permite alimentar o cabeçalho utilizando outros recursos. Acesse o tópico Parâmetros e constantes para mais detalhes.
6. Bloco: crie ou selecione uma função de bloco de programação para alimentar o cabeçalho.
7. Caminho: opção não disponível para Cabeçalhos.
8. Limpar: apaga as configurações feitas no campo.
9. Excluir: exclui o campo.

Tratamento de erros

Se o sistema não encontrar algum item, ele exibirá uma mensagem para o usuário - sendo possível internacionalizar essas mensagens.

Na Figura 3.9, o campo está com uma chave de internacionalização atendendo dois ou mais idiomas.

Figura 3.9 - Aba tratamento de erro

1. Campo Erro de chave primária: mensagem informada ao usuário quando não for possível encontrar algum item.
2. Campo Erro de chave estrangeira: mensagem informada ao usuário quando não for possível encontrar algum item de uma entidade relacionada (foreign key). 
3. Internacionalização: Abre a janela de internacionalização da mensagem;
4. Limpar: exclui o conteúdo preenchido no campo.

Outras informações

Neste tópico veremos algumas configurações específicas para o componente Fonte de dados.

Tipos de eventos

Eventos da fonte de dados permite a execução de uma função ao realizar uma ação. Por exemplo, é possível utilizar os eventos Antes de inserir e Antes de atualizar para validar os campos CPF em um formulário ou enviar uma notificação para o usuário Depois de Inserir um novo registro.

Eventos internos da fonte de dados

Esses eventos estão localizados na aba Eventos (Figura 4.1) e serão executados independente de quem está requisitando a fonte de dados, por exemplo, uma requisição REST à fonte de dados. Essa configuração é feita diretamente nas configurações da fonte de dados, no servidor do sistema, e só é possível selecionar funções do tipo servidor.

Figura 4.1- Seleção de uma fonte de dados ou entidade

Para entender mais sobre quais argumentos utilizar dentro dos seus eventos, acesse o tópico Parâmetros e constantes.

Eventos do componente visual fonte de dados

São eventos JavaScript relacionados apenas ao componente visual fonte de dados (mobile ou web) e aceitam funções cliente ou servidor. Esses eventos só serão executados se a requisição à fonte de dados for feita a partir do componente visual no editor de views. Dessa forma, uma fonte de dados configurada para gerar um serviço REST não executará esses eventos. Eles são inseridos na aba lateral Eventos do componente visual Fonte de dados (Figura 4.2).

Figura 4.2 - Eventos do componente Fonte de dados

Na tabela abaixo é possível visualizar os principais eventos do componente visual fonte de dados. Para mais informações sobre outros eventos, acesse o tópico Eventos da fonte de dados em Eventos dos componentes visuais.

Lançar exceção

Os Eventos do menu lateral do componente Fonte de dados (Figura 4.2) são eventos JavaScript e não podem ser interrompidos. Já os eventos internos da janela da fonte de dados (Figura 3.5) são eventos Servidor, o que significa que uma exceção pode ser adicionada para paralisar o processo. Essas exceções são eventos que quebram o fluxo normal das instruções, assim, ao lançar uma exceção, uma mensagem será exibida na saída do console (Figura 4.3), uma notificação de erro na aplicação.

Na figura 4.3 vemos um exemplo em que uma exceção será lançada caso o usuário cadastrado tenha menos de 18 anos idade.

Figura 4.3 - Bloco para lançar exceção

Na Figura 4.4 lançamos a exceção no evento Antes de Inserir da fonte de dados "Gerenciador de Participantes". Como o evento executa uma ação antes de inserir um dado na fonte de dados e a exceção paralisa o processo, o dado não será cadastrado.

Figura 4.4 - Lançando exceção no evento Antes de Inserir

Veja mais detalhes no tutorial Validação da fonte de dados usando Eventos.

Parâmetros e Constantes

As abas Filtro, Ações, Eventos, Campos, Campos calculados e Cabeçalhos possuem campos onde é possível definir quais valores serão passados. Esses campos podem ser configurados de diversas formas, como veremos a seguir.

A coluna Valor do campo (destaque a da figura 5.1) informa o tipo do valor enquanto a coluna Conteúdo (b) define de onde e como o valor será obtido. A segunda coluna terá um comportamento diferente a depender da seleção da coluna Valor do campo.

Abaixo vemos as opções das caixas de seleção da coluna Valor do campo e o que muda nos campos da coluna Conteúdo (b):

• Estáticos: é composto pela seguintes opções: Texto, Numérico, Data e Hora, Hora ou Lógico.
  • Coluna conteúdo: o campo muda de acordo com a opção escolhida. Exemplo, se a opção "Lógico" for selecionada, o campo ao lado exibirá um checkbox para inserir as opções true ou false. (destaque 2 da figura 5.1)
• Parâmetro: disponível apenas nos campos de Ações das fontes de dados Web Service REST.
  • Coluna conteúdo: cria uma variável que será tratada a partir da aba Filtro. (destaque 3 da figura 5.1)
• Bloco: permite selecionar um bloco de programação que retorne um valor.
  • Coluna conteúdo: exibe um campo onde é possível selecionar um bloco de programação Servidor. (destaque 5 da figura 5.1)
• Expressão: permite criar expressões FTL ou selecionar um item da lista de constantes.
  • Coluna conteúdo: exibe uma caixa de seleção editável onde é possível selecionar/adicionar uma constante Cronapp ou informar uma expressão FTL. (destaques 1, 4 e 6 da figura 5.1)

É possível criar uma variável a partir do caractere : (dois pontos) e uma palavra (ex.: :nome_variavel), o Cronapp reconhecerá como uma variável que será configurada na aba Filtro. Esse artifício pode ser utilizado em diversos momentos, como uma expressões FTL,, textos estáticos ou endPoints de rotas (veja exemplo em parâmetros REST).

Expressões FTL podem ser criadas inserindo o termo "expression:" no início e os caracteres "${}" em cada expressão.

expression: a chave primária do usuário ${data.name} é ${primaryKey}.

Figura 5.1 - Exemplo de janela com diversas formas de configurações de parâmetros

Descrição das configurações na figura 5.1:

1. Variável dois pontos: a variável "parametroDaRota" será configurada na aba Filtro.
2. Valor estático: o texto retornado será "$.data"
3. Parâmetro compartilhado: a variável "variavelParametroCompartilhado" será configurada na aba Filtro.
4. Expressão FTL: retornará o valor da constante limit acrescido de 1.
5. Bloco de programação: alimentado pelo retorno da função MeuBloco.
6. Constante: retornará a chave primária do registro corrente.

Constantes

• NULL: valor nulo.
• queryType: select, count.
• queryStatement: JPQL da query.
• queryFilter: filtro original passado na query OData (ex.: name eq ‘José’).
• queryParameters: mapa com chave/valor dos parâmetros da consulta (ex.: ao usa :<chave> no jpql ou parâmetros de entrada de bloco).
• querySort: campo de ordenação.
• querySortOrder: direção de ordenação (desc/asc).
• simpleFilter: obtém o valor passado para um filtro simples (ex.: name eq ‘José’, o simpleFilter retorna 'José').
• simpleFilterField: obtém apenas o nome do campo de um filtro simples (ex: name eq ‘José’ retorna 'name').
• entityName: retorna a entidade.
• data: retorna o mapa com registro corrente.
• data.(field): informe data.idade para obter o valor "idade" do registro corrente.
• primaryKey: retorna o valor do primaryKey.
• primaryKeys: retorna uma lista com os primaryKeys.
• token: retorna o token de autenticação.
• token.(field): informe token.name para obter o valor "name" do token de autenticação.
• SSOAccessToken: retorna o token do provedor de acesso SSO utilizado.
• expression: retorna uma expressão. Exemplos:
  • Na expressão "${data.name} 123", o valor do campo "name" do registro manipulado será concatenado com a constante "123", retornando: "Thiago 123".
  • Na expressão "${1 + 1}" o valor retornado será "2".
• username: usuário logado.
• role: retorna uma lista com os permissionáveis do sistema.
• top: (paginação) parâmetro top do OData (máximo de registros).
• skip: (paginação) parâmetro skip do OData (quantidade de registros ignorados).
• page: (paginação) facilitador que traz o cálculo (top / skip + 1). Alguns serviços RESTs usam page ao invés de top e skip.
• per_page: (paginação) igual a top.
• limit: (paginação) igual a top.
• now: data e hora atual.
• guid: novo UUID

Exclusivo nos campos da aba Eventos:

• eventName: (exclusivo em parâmetros da aba Eventos) nome do evento que fez a requisição (ex.: onError).

Exclusivos do campo Ao gerar Erro (destaque 1 da figura 5.2) da aba Eventos:

• exception: objeto da exceção.
• exceptionMessage: mensagem da exceção.