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.
• 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 utilizar uma fonte de dados Entidade é 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. Já no tipo Classe, basta selecionar qual Entidade irá alimentar o componente e o Cronapp fará os outros passos automaticamente. 

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 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 (destaque 4 da figura 1.1) ou Configuração de algum outro componente, o ícone é criado automaticamente acima do componente editado na janela de edição da view.

Acesso as propriedades

As propriedades de configuração de uma 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

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 selecionar uma classe ou fonte de dados, 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, pelo ícone do 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. 

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.

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 selecionado;
   • "…": abre janela de seleção de entidade, bloco de programação ou configuração do serviço web;
   • Bloco de programação: abre uma janela para a criação de bloco de programaçã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.

Filtro

Essa aba é responsável por determinar o conjunto de dados que a fonte de dados irá retornar. Em fontes do tipo entidade é possível filtrar por consultas JPQL (destaque 1), essa opção fica desabilitada para Web services ou blocos de programação, que apenas exibirá o nome dos parâmetros do bloco de programação, caso tenha.

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 de 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 fixo 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 o verbo 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 ao campo Entidade base exibirá a opção "Padrão" na lista de funções para as ações (verbos). Essa opção faz a Fonte de dados executar o verbo da forma "padrão", como se a fonte de dados estivesse vinculada a uma Entidade. (Figura 3.4)

O verbo Contar é usado internamente para paginar os registros retornados, porém, para funcionar, os campos Permitir Obter e Permitir Contar devem possuir o mesmo método.

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.
   • Web Service (Rest): é possível definir um endpoint específico para cada ação e adicionar novos parâmetros para essa requisição (Figura 3.4).
   • Web Service (SOAP): é possível selecionar qualquer um dos métodos do serviço SOAP e definir os parâmetros desse método.
   • 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.
3. "…": esse botão ficará habilitado apenas em fontes de dados do tipo Web services e abrem uma janela para personalizar o método SOAP ou endpoint REST.
4. Permissão: define quais permissionáveis podem executar esses verbos.

Ações Web Services

Fontes de dados tipo web services permitem configurar os parâmetros dos métodos do SOAP ou das requisições REST. Após selecionar um método SOAP que possui parâmetros, clique no botão lateral "…" para abrir a janela Obter campo do serviço e configurar o que será passado nos parâmetros. Já para o Rest, além da opção "Padrão" que requisita no formato "URI/{id}", também é possível informar um endpoint diferente, configurando o endereço (URL) e o caminho a ser percorrido no JSON.

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

1. Campo Parâmetro: nome do novo parâmetro a ser passado na requisição.
2. "+": inclui o novo parâmetro na lista.
3. Coluna Nome: lista de parâmetros.
4. Coluna Valor do campo: define o tipo do valor a ser passado, podendo ser tipos fixo (...), Bloco de programação ou Expressões. Veja mais detalhes do tópico Parâmetros e constantes.
5. Remover: remove o parâmetro selecionado.
6. Parâmetros fixos: parâmetros obrigatórios ao personalizar uma ação REST.
   • URL: endereço do endpoint, podendo ser absoluto ou relativo.
   • Caminho: JSON Path a ser percorrido.
7. Parâmetros adicionados: na terceira linha em diante serão apresentados os parâmetros adicionados manualmente.

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 blocos selecionada.
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, permite adicionar novos campos ao mapa retornado e tratar cada campo de forma individual, definindo valores estáticos ou dinâmicos. A adição de novos campos só é possível para fontes do tipo Bloco de programação ou Web service. Não é permitido 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. 

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 fixo (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 JSON Path. 
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 fixo (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.

Configuração do Web Services

Fonte de dados do tipo Web services (REST ou SOAP) possuem uma configuração inicial com alguns passos. Esses passos tem o objetivo de informar a fonte de dados como ela deve tratar os recursos do serviço web.

Ao selecionar a opção Web Services (destaque 1 da figura 4.1), o campo ao lado (destaque 2) ficará habilitável para informar o endereço REST ou SOAP (*.wsdl), em seguida clique no botão Obter campo do serviço (destaque 3) para abrir a janela de configuração.

Figura 4.1 - Informando o endpoint e iniciando a configuração

A primeira janela exibe o campo URL informado e mais os campos dos cabeçalhos Accept e Content-Type usados na requisição. Esse e outros cabeçalhos podem ser configurados posteriormente na aba Cabeçalhos. Por padrão, todos os campos já vêm configurados, clique em Avançar.

Figura 4.2 - Configuração da URL e Cabeçalhos

Na próxima tela, o campo Resultado exibirá o retorno da requisição e o Cronapp tentará preencher automaticamente os dois primeiros campos. Esses campos podem ser editados posteriormente na aba Ações.

• Para Obter:
  • REST: endereço JSON da lista de elementos,
  • SOAP: método do serviço.
• Para Contar: total de elementos usado para a paginação.
  • REST: endereço JSON do campo que informa o total de elementos retornados.
  • SOAP: método do serviço.
• Resultado: retorno da requisição.

Clique em Avançar.

Figura 4.3 - Localizando os dados no JSON

Após identificar a lista de objetos, o Cronapp exibirá um objeto com todos os seus campos em Resultado. 

• Contagem: exibe o total de registros obtidos a partir do endpoint.
• Chaves: o Cronapp tentará identificar qual a chave do objeto, clique no campo para selecionar outros campos chaves. Essa configuração poderá ser feita depois na aba Campos.

Se você estiver obtendo uma requisição SOAP, essa é a última janela, após Avançar o Cronapp retornará as configurações da Fonte de dados.

Figura 4.4 - Configuração dos identificadores do objeto

A janela a seguir permite configurar os campos que serão usados pela fonte de dados. É possível adicionar novos campos e informar o caminho JSON que alimentará o campo. Essa configuração poderá ser feita depois a partir da aba Campos.

Figura 4.5 - Configuração dos campos do serviço REST

A última janela exibirá um objeto com as configurações feitas na tela anterior. Clique em Finalizar para retornar as configurações da fonte de dados.

Figura 4.6 - Resultado final

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 5.1) e serão executados independente que 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 5.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 5.2).

Figura 5.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 5.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 5.3), uma notificação de erro na aplicação.

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

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

Na Figura 5.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 5.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 para  os parâmetros de funções de blocos de programação, cabeçalhos em requisições REST, eventos e muito mais. Esses campos podem ser alimentados com valores fixos, constantes ou com o retorno de um bloco de programação.

Figura 6.1 - configurações de parâmetros

1. Coluna Nome: lista de parâmetros.
2. Coluna Valor do campo: define o tipo do valor a ser passado, podendo ser tipos fixo (...), Bloco de programação ou Expressões
   • Fixos: o valor é definido no próprio parâmetro e podem ser um valor Texto, Numérico, Data e Hora, Hora ou Lógico.
   • Parâmetro: cria parâmetros queryString para as requisições REST a partir das constantes (ex: url/user?username=joao).
   • Bloco: permite selecionar um bloco de programação para retornar um valor.
   • Expressão: permite criar expressões FTL em conjunto com a lista de constantes.
3. Coluna conteúdo: dependendo da opção selecionada no Valor do campo, esse campo se comportará de forma distinta.
   • Fixos: exibirá um campo de data, caso a opção selecionada sela Data ou um campo que só aceita números, no caso de Numérico.
   • Parâmetro: exibirá um dropdown para selecionar uma constante, também é possível configurar o parâmetro queryString.
   • Bloco: exibirá o bloco de programação selecionado.
   • Expressão: exibirá um dropdown para selecionar uma constante, também é possível configurar uma expressão FTL.
4. Remover: remove o parâmetro selecionado.
5. "…": (opção Bloco) abre a janela para selecionar um bloco de programação.
6. Limpar: (opção Bloco) exclui a seleção do bloco.

Abaixo temos uma lista com todas as constantes. Selecione apenas a constante para retornar seu valor, ou elabore uma expressão FTL contendo constantes.

Figura 6.2 - Selecionando argumento para uma função de um campo da aba Eventos

Constantes

• eventName: (exclusivo em parâmetros da aba Eventos) nome do evento que fez a requisição (ex.: onError);
• 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

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

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