Versões comparadas
Chave
- Esta linha foi adicionada.
- Esta linha foi removida.
- A formatação mudou.
Função
A fonte 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 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.
Image Added
Figura 1 - Fluxo de comunicação da Fonte de dados
Informações |
---|
Existe uma diferença entre a A Fonte de dados e o componente visual Fonte fonte de dados, utilizado no Editor de views, são ferramentas diferentes. A fonte Fonte de dados é um recurso criado no lado servidor do projeto e server serve a todos os recursos que necessitam de uma fonte Fonte de dados, já o componente visual fonte de dados é utilizado apenas nas páginas web e telas mobile (lado cliente) e tem o objetivo de referenciar uma Fonte de dados. |
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 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.
Nota |
---|
Não é possível utilizar a mesma fonte de dados para dois componentes na mesma tela, para esses casos, utilize uma segunda fonte de dados. |
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.
Image Removed
Figura 1.1 - Ícone fonte de dados (1) na tela de edição da view
Informações | ||
---|---|---|
| ||
O ícone do componente visual fonte de dados deve estar sempre acima do componente visual no qual ele está associado na tela de edição da view, podendo cada fonte de dados estar logo acima do componente (Figura 1.1) ou todos juntos no início da página. |
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.
Image Removed
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.
condition
Escolhe as condições de carregamento dos dados, que são:
- Padrão: comportamento atual da fonte de dados;
- Todos os Filtros Preenchidos: carrega automaticamente quando todos os filtros forem preenchidos;
- No mínimo um Filtro Preenchido: carrega automaticamente quando pelo menos um dos filtros forem preenchidos;
- Ao Pressionar Botão: carrega apenas ao click de botão que tenha como ação um bloco de programação chamando a função "Carregar fonte de dados".
Dependente de salvamento
Validar Campos Requeridos
Estratégia em Cláusula Nula
Define como o sistema deve tratar parâmetros os nulos do campo "Filtros e Parâmetros" da fonte de dados;
- Padrão: comportamento atual da fonte de dados;
- Limpar Dados: limpa o campo nulo;
- Remover Cláusula: só considera as cláusulas preenchidas;
- Aguardar Preenchimento: não executa até que todas estejam preenchidas.
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.
Image Removed
Figura 2.1 - Janela de Filtros e Parâmetros
- Configuração do Grupo: define o condicional entre suas regras e outros grupos;
- Campo de seleção de condicional (e / ou) do grupo;
- Adiciona nova regra a esse grupo;
- Adiciona novo grupo filho;
- Exclui grupo (não é possível excluir o primeiro grupo da hierarquia);
- Configuração da Regra: define um elemento de comparação entre um atributo da fonte de dados e outro elemento;
- Seleciona o atributo da fonte de dados;
- Seleciona o operador de comparação (=; ≠; <; >; <= ou >=);
- Seleciona o tipo do que será comparado: expressão, booleano, String e outros;
- Campo para informar o que será comparado: expressões, data, String, bloco de programação ou outros;
- 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;
- Exclui regra.
Image Removed
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:Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
(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).
Image Removed
Figura 2.3 - Ordenação do campo 'name' em ordem crescente
- Adiciona uma nova ordenação;
- Seleciona o campo da fonte de dados que será o ordenador;
- 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.
Image Removed
Figura 2.4 - Ligação entre o atributo id da fonte de dados e o id de outra fonte de dados da view
- Adiciona uma nova ligação;
- Seleciona o atributo da fonte de dados principal;
- Operador de comparação igual (único possível);
- Seleciona o tipo do que será comparado: expressão, booleano, String e outros;
- Atributo da fonte filho, que pode ser: expressões, bloco de programação, campo da tela ou outros;
- 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);
- 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.
Dica |
---|
Fontes de dados do tipo Entidades são alimentadas apenas por uma classe e permite personalizações, já as fontes de dados do tipo Classe não permitem nenhum tipo de personalização, retornando todos os registros. |
Image Removed
Figura 2.5 - Seleção de uma fonte de dados ou entidade
- Coluna nome: separa em níveis as fontes de dados por seus tipos (Bloco de programação, Classe, Entidade, Web Services).
- Coluna Tipo: informa se o item é uma fonte de dados ou entidade.
- 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.
- Coluna Editar: abre a janela de edição da fonte de dados.
- 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: /
Tooltip | ||||
---|---|---|---|---|
| ||||
Endereç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).
Image Removed
Figura 3.1 - Acesso as fontes de dados pelo menu do sistema
- Ícone Fonte de dados: abre a janela "Buscar Fonte de Dados" onde é possível criar, editar ou excluir fontes de dados.
- 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).
- 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.
- 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.
- 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.
- 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.
- Editar: abre a janela de edição da fonte de dados.
- 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).
Image Removed
Figura 3.2 - Janela de edição da fonte de dados
- 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.
- Copiar URL: copia o URN da fonte de dados.
- 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.
- Nome da consulta: nome que identifica a consulta para o programador no momento da seleção das fontes de dados.
- Tipo da fonte: define se a fonte de dados estará vinculada a uma entidade, bloco de programação ou web service.
- 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.
- 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.
- Auditoria em Log: habilita o sistema de auditoria para essa fonte de dados. Acesse a documentação Log de Auditoria para mais detalhes.
- Aba Filtro: define uma consulta JPQL ou parâmetros da função dos blocos de programação.
- Aba Ações: define permissões para os verbos HTTP.
- Aba Eventos: chama ações em diversos momentos da execução da fonte de dados.
- Aba Campos: altera o valor de cada campo e dá permissões diferenciada aos permissionáveis.
- Aba Campo calculados: adiciona novos campos ao mapa retornado da fonte de dados.
- Aba Cabeçalhos: adiciona cabeçalho em fonte de dados via Web Services.
- Aba Tratamento de erros: adiciona mensagens de erros personalizadas, permite internacionalização dessas mensagens.
Informações | ||
---|---|---|
| ||
Independente do tipo da fonte de dados, é possível usá-la para gerar recursos REST dentro e fora do sistema. O endPoint do recurso fica localizado ao lado do campo Identificador (destaque 1 da Figura 3.2) e deve ser concatenado com o domínio do sistema. Sintaxe: Vale lembrar que poderá ser necessário aplicar permissões na fonte de dados e em seus campos. Para mais detalhes, acesse a documentação Disponibilizando Web Service REST. |
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.
Image Removed
Figura 3.2.1 - Janela de edição da fonte de dados do tipo Web Services
Dica |
---|
Para mais detalhes sobre como configurar uma fonte de dados a partir de web services, acesse a documentação Fonte dados tipo Web Service (REST / SOAP). |
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).
Informações |
---|
Acesse o tópico aba Ações para mais detalhes sobre como configurar os parâmetros das fontes de dados Web Services. |
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.
Image Removed
Figura 3.3 - Exemplo de filtro para uma entidade
- Consulta JPQL: exibe a consulta JPQL criada (habilitado somente quando a fonte está vinculada a uma entidade).
- Editar: abre uma janela para a criação da consulta JPQL em modo visual (habilitado somente quando a fonte está vinculada a uma entidade).
- 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.
- 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.
- "…": seleciona uma função de bloco para ser a fonte desse campo.
- Novo bloco: cria bloco de programação e uma função.
- 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).
Dica | ||
---|---|---|
| ||
O verbo Para Contar é usado internamente para paginar os registros retornados, porém, para funcionar, os campos Para Obter e Para Contar devem possuir as mesmas configurações. |
Image Removed
Figura 3.4 - Configurando a ação Remover para uma fonte de dados do tipo Web service REST
- Coluna Ações: ativa ou desativa cada um dos verbos HTTP.
- 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).
- "…": 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.
- 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 endPointdas 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).Dica |
---|
Para mais detalhes sobre como configurar uma fonte de dados a partir de web services, acesse a documentação Fonte dados tipo Web Service (REST / SOAP). |
Image Removed
Figura 3.4.1 - Configurando ação ações para uma fonte de dados web service REST
- "...": abre a janela "Obter campos do serviço" para personalizar os parâmetros do método SOAP ou endpoint REST em cada ação.
- Campo Parâmetro: (só disponível em Web Service REST) nome do novo parâmetro a ser passado na requisição.
- "+": (só disponível em Web Service REST) inclui o novo parâmetro na lista de queryStrings.
- Coluna Nome: lista de parâmetros.
- 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.
- Remover: (só disponível em Web Service REST) remove o parâmetro selecionado.
- 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
- Exemplo
- 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
- Situação 1 - Campo URL com o caractere "
- 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
- Exemplo
- Campo vazio: a requisição será feita a partir de "
- 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 atributodata
no JSON). Caso não seja preenchido, será obtido todo o conteúdo do corpo da requisição.
- URL: substitui ou personaliza o endPoint da URL Base:
- 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.
- 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.
- 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).
Image Removed
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).
Bloco de código | ||||
---|---|---|---|---|
| ||||
DELETE https://607f375302a23c0017e8cec5.mockapi.io/user?id_user=123&token=ABC321 |
Informações |
---|
O uso da aba Filtro para alimentar parâmetros de requisições REST também pode ser feito em requisições que utilizam o modelo de rotas. Nesse caso, podemos informar " Veja mais detalhes sobre isso no tópico Parâmetros REST. |
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.
Bloco de código | ||||
---|---|---|---|---|
| ||||
https://meusistema.com.br/comentarios/list?postId=4&id=17 |
Image Removed
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
".
Bloco de código | ||||
---|---|---|---|---|
| ||||
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.
Image Removed
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.
Image Removed
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.
Image Removed
Figura 3.5 - Seleção de uma fonte de dados ou entidade
Colunas
- Eventos: lista de eventos.
- Campo: exibe as funções de bloco selecionadas.
- "…": abre a janela para seleção da função.
- Criar bloco: cria novo bloco de programação com uma função.
- 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.
Image Removed
Figura 3.6 - Aba campos e as várias configurações de seus atributos
- Campo a adicionar: nome do campo a ser adicionado. Esse campo não é exibido em fontes de dados do tipo Entidade.
- 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.
- Nome dos campos: coluna com o nome dos campos.
- 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.
- Conteúdo: permite alimentar o campo utilizando outros recursos. Acesse o tópico Parâmetros e constantes para mais detalhes.
- Tipo do campo: define o tipo do campo.
- Permite nulo: define se o campo aceitará valores nulos.
- Chave: define se o campo é uma das chaves primárias da entidade.
- Bloco: crie ou selecione uma função de bloco de programação para alimentar o campo.
- 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
). - Permissões: define restrições aos permissionáveis cadastrados no sistema.
- Limpar: apaga as configurações feitas no campo.
- 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.
Image Removed
Figura 3.7 - Aba de campos calculados
- Campo a adicionar: nome do campo a ser adicionado.
- Adicionar campo: insere o campo calculado.
- Nome dos campos: coluna com o nome dos campos.
- 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.
- Conteúdo: permite alimentar o campo utilizando outros recursos. Acesse o tópico Parâmetros e constantes para mais detalhes.
- Tipo do campo: define o tipo do campo.
- Bloco: crie ou selecione uma função de bloco de programação para alimentar o campo.
- Caminho: opção não disponível para Campos calculados.
- Permissões: define restrições aos permissionáveis cadastrados no sistema.
- Limpar: apaga as configurações feitas no campo.
- 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
.
Image Removed
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.
Image Removed
Figura 3.9 - Aba Cabeçalhos de uma fonte de dados Web Services
- Campo a adicionar: nome do cabeçalho a ser adicionado.
- Adicionar campo: insere o novo cabeçalho.
- Nome dos cabeçalhos: coluna com o nome dos cabeçalhos.
- 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.
- Conteúdo: permite alimentar o cabeçalho utilizando outros recursos. Acesse o tópico Parâmetros e constantes para mais detalhes.
- Bloco: crie ou selecione uma função de bloco de programação para alimentar o cabeçalho.
- Caminho: opção não disponível para Cabeçalhos.
- Limpar: apaga as configurações feitas no campo.
- 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.
Image Removed
Figura 3.9 - Aba tratamento de erro
- Campo Erro de chave primária: mensagem informada ao usuário quando não for possível encontrar algum item.
- 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).
- Internacionalização: Abre a janela de internacionalização da mensagem;
- 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.
Image Removed
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).
Image Removed
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.
Nome
Função
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.
Image Removed
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.
Image Removed
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.
Bloco de código | ||||
---|---|---|---|---|
| ||||
expression: a chave primária do usuário ${data.name} é ${primaryKey}. |
Image Removed
Figura 5.1 - Exemplo de janela com diversas formas de configurações de parâmetros
Descrição das configurações na figura 5.1:
- Variável dois pontos: a variável "
parametroDaRota
" será configurada na aba Filtro. - Valor estático: o texto retornado será "$.data"
- Parâmetro compartilhado: a variável "
variavelParametroCompartilhado
" será configurada na aba Filtro. - Expressão FTL: retornará o valor da constante
limit
acrescido de 1. - Bloco de programação: alimentado pelo retorno da função
MeuBloco
. - 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".
- Na expressão "
- 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 detop
eskip
.Dica Por padrão, ao requisitar a primeira página, a constante
page
retorna o valor 1. Porém, existem API's que possuem a página 0 e consideram a página 1 como a segunda página. Nesses casos, o recomendado é usar uma expressão FTL no campo:${page - 1}
.- 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.
, fazendo a comunicação entre os demais componentes visuais (exemplo Grade) e a Fonte de dados referenciada. |
Âncora tipos tipos
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.
Image Added
Figura 2 - Tipos de Fonte de dados
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/
Tooltip | ||||
---|---|---|---|---|
| ||||
Endereço: |
) (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).
Image Added
Figura 3 - Acesso a lista de Fontes de dados
- Janela Buscar Fonte de Dados: lista as Fontes de dados do projeto e permite criar, editar, duplicar ou excluir.
- 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.
- A árvore de recurso lista as Fontes de dados de forma hierárquica, exibindo diretórios e subdiretórios.
- Subdiretório: utilize subdiretórios para organizar as Fontes de dados de acordo as necessidades do projeto.
- 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).
- 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.
- 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.
- Editar: abre a janela de edição da Fonte de dados.
- Excluir: apaga a Fonte de dados selecionada.
- Duplicar: faz uma cópia da Fonte de dados selecionada.
- 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.
- Botão Nova Fonte de dados: abre a janela para configurar uma nova Fonte de dados.
- Botão Selecionar: abre a janela de configuração da Fonte de dados selecionada.
Informações |
---|
Acesse o tópico Drag and Drop a ações da Fonte de dados para conhecer outras funções geradas pelos arquivos da Fonte de dados. |
Âncora criarConfigurar criarConfigurar
Criar e Configurar
É possível criar uma Fonte de dados por vários caminhos:
Na estrutura de arquivos, posicione o mouse sobre o diretório Fontes de Dados (destaque 2 da figura 3) (Localização:
/Fontes de Dados/
Tooltip onlyIcon true appendIcon info-circle Endereço:
src/main/java/META-INF/datasources/
), clique no ícone (+) ao lado e selecione Fonte de dados.
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/
Tooltip onlyIcon true appendIcon info-circle Endereço:
src/main/java/META-INF/datasources/
) e acesse Novo > Fonte de dados.
- Na janela Buscar Fonte de Dados, clique no botão Nova Fonte de dados (10 da figura 3).
- 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 5 da Figura 4), Tipo da Fonte de dados (6) e Origem dos dados (7).
Image Added
Figura 4 - Janela de edição da Fonte de dados
- Identificador: identificador único da Fonte de dados no projeto, não aceita espaços ou caracteres especiais.
- A Fonte de dados sempre é criada com um identificador padrão único e imutável (ex.: "query123456"), ao modificar esse campo, um segundo identificador é criado e a Fonte de dados passará a atender ambas requisições, isso possibilita gerar endereços REST (2) personalizados. Internamente, o Cronapp sempre utilizará o identificador padrão.
- 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).
- Copiar URL: copia o URN da Fonte de dados.
- 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.
- 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.
- Tipo da fonte: define o tipo da Origem dos dados (7), 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).
- 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" (6).
- 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.
- 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).
- 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.
- Aba Filtro: define uma consulta JPQL ou SQL e permite tratar os filtros e parâmetros criados nas configurações da Fonte de dados.
- Aba Ações: define permissões para os verbos HTTP.
- Aba Eventos: chama ações em diversos momentos da execução da Fonte de dados.
- Aba Campos: configura os atributos (campos) dos objetos e dá permissões diferenciadas a partir dos permissionáveis.
- Aba Campos calculados: adiciona novos campos ao mapa da Fonte de dados.
- Aba Cabeçalhos: adiciona cabeçalho em Fonte de dados via Web Services.
- Aba Tratamento de erros: adiciona mensagens de erros personalizadas, permite internacionalização dessas mensagens.
Âncora abaFiltro abaFiltro
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.
- 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.
- 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.
Image Added
Figura 4.1 - Exemplo de filtro para uma entidade
- Consulta: exibe a consulta JPQL ou SQL, esse campo estará desabilitado para as Fontes de dados Bloco de programação e Web Service.
- 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.
- Nome do parâmetro: nome do filtro/parâmetro.
- 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.
- "…": seleciona uma função de bloco de programação servidor para alimentar o filtro.
- Novo bloco: cria função de bloco de programação servidor para alimentar o filtro.
- Limpar: apaga a configuração do filtro.
Âncora abaAcoes abaAcoes
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.
Dica | ||
---|---|---|
| ||
O verbo Para Contar é usado internamente para paginar os registros retornados, porém, para funcionar, as ações Para Obter e Para Contar devem possuir as mesmas configurações. |
Image Added
Figura 4.2 - Aba Ações da Fonte de dados
- Coluna Ações: nome da ação com um checkbox para ativar ou desativar cada ação (verbos HTTP).
- 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".
- 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.
- 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.
- "…": 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).
Permissão: define quais permissionáveis podem executar a ação configurada.
Dica As permissões aplicadas na aba Ações serão herdadas para todos os atributos nas abas Campos e Campos calculados. Por exemplo, ao selecionar a permissão "Administradores" do verbo Para Obter na aba Ações, todos os atributos terão os seus campos Permitir Obter (destaques 11 da figura 4.4 e 9 da figura 4.5) configurados automaticamente para "Administradores".
Informações | ||
---|---|---|
| ||
Se o campo "Entidade base" (destaque 8 da figura 4) estiver configurado, será possível selecionar a opção "Padrão" na caixa de seleção de cada ação. Essa opção faz com que a ação seja executada da mesma forma como ocorre nas Fontes de dados do tipo Consulta a Entidades. Assim, a lista de dados pode ser obtida via bloco de programação, mas as demais ações (inserir, atualizar e remover) serão executadas no banco de dados através da classe selecionada no campo "Entidade base". Acesse a documentação Tratar recurso REST de terceiros no Cronapp e veja exemplos de como tratar recursos de paginação, ordenação e filtro com Fonte de dados do tipo Bloco de programação. |
Âncora abaEventos abaEventos
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.
Informações |
---|
Existem diferenças entre os eventos da Fonte de dados (Figura 4.3) e os eventos do componente visual fonte de dados. O componente visual trata os dados do lado cliente (JavaScript) e seus eventos não podem ser interrompidos, já os Eventos da Fonte de dados (Java) podem ser paralisados a partir de exceções em seu 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 e uma notificação de erro na aplicação (veja mais detalhes sobre exceções em Validação da fonte de dados usando Eventos). |
Image Added
Figura 4.3 - Aba Eventos da Fonte de dados
Colunas
- Eventos: lista de eventos.
- Campo: exibe a função de bloco de programação selecionada.
- "…": abre a janela para seleção da função.
- Novo bloco: cria função de bloco de programação servidor para alimentar o evento.
- 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.
Âncora abaCampos abaCampos
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.
Image Added
Figura 4.4 - Aba campos e as várias configurações de seus atributos
- Campo a adicionar: nome do novo atributo.
- Adicionar campo: insere o atributo informado (1).
- Nome dos campos: coluna com o nome dos atributos.
- 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).
- 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).
- Permite nulo: define se o campo aceitará valores nulos.
- Chave: define se o campo é uma das chaves primárias da entidade.
- "...": 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>
oudata
para enviar o objeto completo. - Bloco: cria uma função de bloco de programação para alimentar o campo.
- 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)
- Web Service: permite informa o caminho (JSON Path) do atributo que irá alimentar o campo (ex,:
Permissões: define restrições para cada verbo aos permissionáveis cadastrados no sistema.
Informações As configurações das permissões feitas na aba Ações serão herdadas automaticamente para cada atributo. Após a herança de permissões, ainda será possível ajustar as permissões individualmente em cada atributo.
- Limpar: apaga as configurações feitas no atributo.
- Excluir: exclui o atributo.
Âncora abaCamposCalculados abaCamposCalculados
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.
Informações |
---|
Os campos calculados podem não funcionar em recursos que rodem internamente no Cronapp (como é o caso da aba Pré-visualizar do Relatório e Dashboard), sendo exibidos somente ao executar a aplicação. |
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.
Image Added
Figura 4.5 - Aba de campos calculados
- Campo a adicionar: nome do novo atributo.
- Adicionar campo: insere o atributo informado (1).
- Nome dos campos: coluna com o nome dos campos calculados.
- 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).
- 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).
- "...": 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>
oudata
para enviar o objeto completo. - Bloco: cria uma função de bloco de programação para alimentar o campo.
- Caminho: opção não disponível para Campos calculados.
Permissões: define restrições para cada verbo aos permissionáveis cadastrados no sistema.
Informações As configurações das permissões feitas na aba Ações serão herdadas automaticamente para cada atributo de campo calculado. Após a herança de permissões, ainda será possível ajustar as permissões individualmente em cada campo.
- Limpar: apaga as configurações feitas no atributo.
- 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
.
Informações |
---|
Além da Fonte de dados do tipo Consulta a Entidades, esse recurso também estará disponível para os tipos Bloco de programação e Web Services, desde que tenha uma Entidade vinculada no campo Entidade base (destaque 8 da figura 4). |
Image Added
Figura 4.5.1 - Campos calculados referenciando atributos de outras entidades relacionadas
Âncora abaCabecalhos abaCabecalhos
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.
Dica |
---|
Os cabeçalhos da janela "Obter campos do serviço" (destaque a da figura 4.6) não aceitam valores dinâmicos (função de blocos de programação ou expressão), dessa forma, ao configurar um cabeçalho com valor dinâmico na aba Cabeçalhos e depois acessar a janela "Obter campos do serviço" (destaque a), o cabeçalho estará vazio e será necessário informar o valor estático. Veja mais detalhes em Fonte de dados tipo Web Service (REST / SOAP). |
Image Added
Figura 4.6 - Aba Cabeçalhos de uma Fonte de dados Web Services
- Campo a adicionar: nome do novo cabeçalho.
- Adicionar campo: insere o cabeçalho informado (1).
- Nome: coluna com o nome dos cabeçalhos.
- Valor do cabeçalho: define um valor estático ou dinâmico para alimentar o cabeçalho. Acesse o tópico Parâmetros e Constantes para mais detalhes sobre valores dinâmicos (Expressão).
- "...": selecione uma função bloco de programação servidor existente para alimentar o cabeçalho.
- Bloco: crie uma função de bloco de programação para alimentar o cabeçalho.
- Caminho: opção não disponível para cabeçalhos.
- Limpar: apaga as configurações feitas no cabeçalho.
- Excluir: exclui o cabeçalho.
Âncora abaTratamentoErros abaTratamentoErros
Aba Tratamento de erros
Essa aba é utilizada para exibir uma mensagem amigável para o usuário caso ocorra algum erro ou a Fonte de dados não encontre chaves primárias e estrangeiras dos objetos manipulados. Essas mensagens podem ser internacionalizadas.
Nota |
---|
Esse recurso ainda não está disponível para as Fontes de dados do tipo SQL Nativo. |
Image Added
Figura 4.7- Aba tratamento de erro
Colunas
- Campos: lista de opções para tratamento de erros.
- Valor: aceita textos estáticos ou chave de internacionalização.
- Internacionalização: Abre a janela de internacionalização da mensagem.
- Limpar: exclui o conteúdo preenchido no campo.
Opções de tratamento
- Erro de chave primária: mensagem informada ao usuário quando não for possível encontrar algum item (primary key).
- Erro de chave estrangeira: mensagem informada ao usuário quando não for possível encontrar algum item de uma entidade relacionada (foreign key).
Outras informações
Neste tópico veremos mais detalhes da Fonte de dados.
Âncora dragDropAcoes dragDropAcoes
Drag and Drop a ações da Fonte de dados
Os arquivos da Fonte de dados (Localização: /Fonte de Dados/
Tooltip | ||||
---|---|---|---|---|
| ||||
Endereço: |
) na árvore de recursos podem ser arrastados (drag and drop) até o Editor de views para gerar componentes visuais já vinculados com o componente visual fonte de dados. Ao arrastar, o menu de contexto Criar Componente exibirá as opções abaixo, variando se o Editor selecionado for web ou mobile:
- Caixa de seleção dinâmica:
- Web: abre a janela de configuração da Caixa de seleção dinâmica (web).
- Mobile: abre a janela de configuração da Caixa de seleção dinâmica (mobile).
- Crud:
- Web: abre a janela do Assistente de view para entidade com as opções dos formulários Web.
- Mobile: abre a janela do Assistente de view para entidade com as opções dos Formulários mobile.
- Grade/Lista avançada:
- Web: abre a janela de configuração do componente Grade (web).
- Mobile: abre a janela de configuração do componente Lista Avançada (mobile).
Image Added
Figura 5 - Adicionando componentes visuais no Editor de Formulários a partir da Fonte de dados
Outro recurso interessante gerado a partir dos arquivos da Fonte de dados é o item Ação do seu menu de contexto, ele exibe opções para gerar páginas CRUDs com o Assistente de CRUD ou gerar um relatório, com os atributos da Fonte de dados (veja mais detalhes no tópico "Criar relatórios" da documentação Relatório).
Image Added
Figura 5.1 - Item Ação do menu de contexto dos arquivos da Fonte de dados
Âncora | ||||
---|---|---|---|---|
|
Parâmetros e Constantes
A janela de configurações de parâmetros (Figura 6) está disponível em diversos locais dentro do Cronapp e também nas abas Filtro, Ações, Eventos, Campos, Campos calculados e Cabeçalhos da Fonte de dados. Ela permite definir os parâmetros que serão passados e seus valores.
A depender do local em que essa janela for aberta, algumas características podem mudar. Por exemplo, a possibilidade de incluir novos parâmetros a partir dessa janela ou selecionar as opções "Bloco" ou "Parâmetro" na coluna Valor do campo. Abaixo vemos a janela de seleção de Parâmetros da Aba Ações da Fonte de dados do tipo Web Services, em que é possível personalizar os parâmetros (QueryString) passados por cada ação.
Image Added
Figura 6 - Exemplos de tipos de parâmetros da janela de configuração das ações
Os 4 itens abaixo representam as opções da coluna Valor do campo (destaque a da figura 6) e o que muda nos campos da coluna Conteúdo (essa coluna não possui um nome, mas está destaca pela letra b na figura 6):
- Estáticos: possui as seguintes opções: Texto, Numérico, Data e Hora, Hora ou Lógico.
- Coluna conteúdo: (destaque b da figura 6) 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.
- Parâmetro Compartilhado: disponível apenas nos campos da aba Ações das fontes de dados Web Service REST, essa opção permite criar uma variável que será alimentada a partir da aba Filtro e poderá ser utilizada nas configurações de todas as ações dessa Fonte de dados.
- Coluna conteúdo: (destaque b da figura 6) o campo conteúdo exibirá um campo de texto para informar o nome da variável. É possível criar uma variável ao selecionar "Parâmetro" na coluna Valor do campo (a) e informar um nome no campo conteúdo (b) ou selecionar a opção "Expressão" e no campo conteúdo (b) informar um nome com o caractere dois-pontos na frente (ex,: "
:minhaVar
"). Os parâmetros destacados no item 2 da figura 6 possuirão o mesmo resultado.
- Coluna conteúdo: (destaque b da figura 6) o campo conteúdo exibirá um campo de texto para informar o nome da variável. É possível criar uma variável ao selecionar "Parâmetro" na coluna Valor do campo (a) e informar um nome no campo conteúdo (b) ou selecionar a opção "Expressão" e no campo conteúdo (b) informar um nome com o caractere dois-pontos na frente (ex,: "
- Bloco: permite executar uma função de bloco de programação servidor com retorno. Caso o bloco possua parâmetro, é possível passar como argumento uma lista de constantes, uma expressões FTL ou criar parâmetro compartilhando (2).
- Coluna conteúdo: (destaque b da figura 6) exibe um campo onde é possível selecionar um bloco de programação Servidor.
- Expressão: permite selecionar um item da lista de constantes ou criar expressões FTL.
- Coluna conteúdo: (destaque b da figura 6) exibe uma caixa de seleção editável onde é possível selecionar/adicionar uma constante Cronapp ou informar uma expressão FTL.
Âncora | ||||
---|---|---|---|---|
|
Expressão
A opção Expressão na coluna Valor do campo (destaque a da figura 6) dará acesso a uma caixa de seleção editável onde é possível selecionar constantes Cronapp ou incluir uma expressões FTL (FreeMarker Template Language).
Com o uso de expressões FTL é possível incluir pequenos cálculos ou gerar pequenos templates diretamente no campo Conteúdo (destaque b da figura 6). Esse recurso pode ser bem útil no caso de parâmetros simples, porém, ao necessitar de algo um pouco mais complexo, recomendamos fortemente utilizar uma função de bloco de programação servidor.
Expressões FTL são criadas inserindo o termo "expression:
" e os caracteres "${ <conteúdo> }
" em cada expressão (destaque 4 da figura 6).
Bloco de código | ||||
---|---|---|---|---|
| ||||
expression: ${page - 1} |
O resultado da expressão contida no bloco acima será o valor da constante "page" subtraído de 1.
Nota |
---|
Fique atento aos pontos abaixo ao trabalhar com expressões FTL e constantes Cronapp:
|
Para fazer conversões simples dentro de expressões FTL, como converter tipo string para number, basta incluir "?number
" e forçar a conversão.
Bloco de código | ||||
---|---|---|---|---|
| ||||
expression: ${skip?number + 2} |
Se o retorno da constante "skip" no exemplo do bloco acima for "3" e não for utilizado o recurso "?number", o resultado final será "32" ao invés de "5", pois a expressão irá concatenar os 2 valores. Já ao utilizar o "?number", o resultado será "5", como esperado.
Clique aqui e veja mais detalhes sobre conversões FTL.
Âncora | ||||
---|---|---|---|---|
|
Constantes
As constantes Cronapp são selecionáveis nos campos da coluna Valor do campo (destaque a da figura 6) em várias janelas, como as de configuração dos parâmetros query String, filtros e parâmetros de funções, elas retornam o valor do que foi selecionado. Algumas dessas constantes também são aceitas dentro de expressões FTL (veja exemplos de uso no tópico Expressão).
Veja a lista de Constantes:
- NULL: retorna nulo.
- queryType: retorna o tipo da requisição OData (ex: select, count).
- queryStatement: requisição ODATA.
- queryFilter: filtro original passado na query OData (ex.: name eq ‘José’).
- queryParameters: mapa com chave/valor dos parâmetros da consulta OData (ex.: ao usar
:<chave>
no jpql ou parâmetros de entrada de bloco). - querySort: campo de ordenação na consulta OData.
- querySortOrder: direção de ordenação (desc/asc) da consulta OData.
- simpleFilter: obtém o valor passado para um filtro simples OData (ex.: name eq ‘José’, o simpleFilter retorna 'José').
- simpleFilterField: obtém apenas o nome do campo de um filtro simples OData (ex.: name eq ‘José’ retorna 'name').
- entityName: retorna a entidade da consulta OData.
- data: objeto contendo os atributos do registro corrente. Ver mais detalhes no tópico abaixo.
- data.{field}: valor do atributo informado no registro corrente (ex.:
data.idade
para obter o valor de "idade"). - formData: objeto contendo os atributos do registro corrente. Ver mais detalhes no tópico abaixo.
- formData.{field}: valor do atributo informado no registro corrente (ex.:
data.idade
para obter o valor de "idade"). - rawEntry: mapa contendo todos os atributos da requisição. Ver mais detalhes no tópico abaixo.
- rawEntry.{field}: valor do atributo informado no mapa da requisição (ex.:
data.idade
para obter o valor de "idade"). - primaryKey: retorna o valor do primaryKey.
- primaryKeys: retorna uma lista com os primaryKeys.
- token: retorna o objeto do token de autenticação.
- token.{key}: valor do atributo do token (ex.:
token.name
para obter o valor do atributo "name" do token de autenticação). - SSOAccessToken: retorna o token do provedor de acesso SSO utilizado.
- session.{key}: valor da variável do tipo de autenticação Sessão. Apesar de existir a constante, não aconselhamos utilizar o tipo de autenticação Sessão no Cronapp.
- expression:{value}: retorna uma expressão FTL criada. Exemplos:
- Na expressão "
expression:${1 + 2}
" o valor retornado será "3".
- Na expressão "
- username: usuário logado.
- roles: 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, único que retorna um valor inteiro) facilitador que traz o cálculo (top / skip + 1). Alguns serviços RESTs usam
page
ao invés detop
eskip
.Dica Por padrão, ao requisitar a primeira página, a constante
page
retorna o valor 1. Porém, existem API's que possuem a página 0 e consideram a página 1 como a segunda página. Nesses casos, o recomendado é usar uma expressão FTL no campo conteúdo (destaque b da figura 6):expression: ${page - 1}
- per_page: (paginação) igual a top.
- limit: (paginação) igual a top.
- applicationId: identificador da aplicação em execução, mais detalhes em Multi aplicações.
- offset: (paginação) igual a skip.
- 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 4.3) da aba Eventos:
- exception: objeto da exceção.
- exceptionMessage: mensagem da exceção.
Âncora | ||||
---|---|---|---|---|
|
Diferenças data, formData e rawEntry
As 3 constantes retornaram o objeto manipulado antes de ser inserido, atualizado ou removido. Após inserir ou modificar, o atributo pode sofrer modificações por eventos da Fonte de dados ou ações no banco de dados (ex.: valores default, triggers, auto incrementos etc).
A constante rawEntry
retorna o mapa completo da requisição enviada pela Fonte de dados (ex.: POST), possui o objeto da entidade vinculada com a Fonte de dados, campos calculados, metadatas, URI da requisição e outras informações. Já as constantes formData
e o data
funcionam de forma parecida, retornando apenas o objeto da entidade vinculada com a Fonte de dados. A constante data
é mais antiga e apenas consta na lista de constantes para manter compatibilidade com projetos mais antigos.
Imagine uma Fonte de dados vinculada a classe Application
do Diagrama de dados que possui apenas 2 atributos (id
e name
), essa Fonte de dados teve sua consulta personalizada (bloco de código abaixo) e foi incluído um campo calculado de nome "campoCalculado
".
Bloco de código | ||
---|---|---|
| ||
select
a.id,
a.name,
concat('Techne - ', a.name) as fullName
from
Application a |
O retorno das 3 constantes na chamada do evento Antes de Inserir será:
- rawEntry:
{"mediaMetadata": {"sourceLink":null, "etag":null, "contentType":null, "editLink":null}, "expandSelectTree": {"properties":[], "links":{}, "explicitlySelected":false, "expanded":false, "allKind":"IMPLICITLYTRUE", "all":true}, "metadata":{"id":null, "etag":null, "uri":null}, "properties":{"campoCalculado":"conteúdo do campo calculado", "_objectKey":"6F01513D-9953-43F7-ADEF-B08CC7763252", "name":"Cronapp", "fullName":null, "id":"6F01513D-9953-43F7-ADEF-B08CC7763252"}}
- formData:
{"id":"6F01513D-9953-43F7-ADEF-B08CC7763252", "name":"Cronapp"}
- data:
{"id":"6F01513D-9953-43F7-ADEF-B08CC7763252", "name":"Cronapp"}
Âncora | ||||
---|---|---|---|---|
|
Parâmetros de Query String
A Fonte de dados trabalha em cima do padrão OData, dessa forma, os recursos dessa tecnologia (filtro, conversão, paginação, ordenação e outros) funcionarão com a Fonte de dados. Veja na documentação oficial mais detalhes sobre os parâmetros utilizados pelo OData.
Dica |
---|
Os parâmetros apresentados nesse tópico são úteis, por exemplo, quando se quer obter os dados de uma Fonte para alimentar um sistema desenvolvido fora do Cronapp. Os Componentes visuais e demais recursos do Cronapp já são preparados para trabalhar de forma integrada, sem a necessidade desse nível de configuração. |
É possível obter os parâmetros passados em uma transação com a Fonte de dados utilizando o bloco de programação Obter parâmetro da query string. Veja um exemplo de uso desse recurso no tutorial Tratar recurso REST de terceiros no Cronapp.
- $filter: permite filtrar os registros retornados a partir de regras, para isso, existem diversos operadores lógicos, aritméticos e funções.
- Valores aceitos: acesse a documentação oficial para mais detalhes de como configurar o parâmetro filtro.
- Exemplo: a requisição abaixo retornará apenas registros em que o atributo "price" seja maior ou igual a "20".
<URI_da_FonteDados>?$filter=Price gt 20
- Exemplo 2: a requisição abaixo retornará apenas registros em que o atributo "price" seja maior ou igual a "20" e que o ano do atributo "ReleaseDate" seja igual a "2006".
<URI_da_FonteDados>?$filter=Price gt 20 and year(ReleaseDate) eq 2006
- $format: por padrão, a Fonte de dados Cronapp sempre retorna seus dados em formato XML, porém é possível alternar para JSON.
- Valores aceitos: aceita os valores "xml" ou "json".
- Exemplo: a requisição abaixo retornará a lista de objetos em formato JSON.
<URI_da_FonteDados>?$format=json
- $inlinecount: inclui o atributo "__count" na raiz do objeto de retorno de requisição, o valor desse atributo corresponde ao número total de registros na base de dados, ignorando qualquer filtro passado. Esse recurso é utilizado para realizar paginação.
- Valores aceitos: aceita os valores "allpages" ou "none", o valor "none" equivale a não informar o atributo "$inlinecount".
- Exemplo: a requisição abaixo retornará apenas os 2 primeiros registros, porém no atributo "__count" exibirá o valor do total de registros na base de dados.
<URI_da_FonteDados>?$top=2&$inlinecount=allpages
- $orderby: ordena a lista requisitada a partir de um atributo do objeto.
- Valores aceitos: necessário informar o nome do atributo mais "asc" para ascendente ou "desc" para descendente.
- Exemplo: a requisição abaixo retorna uma lista onde os objetos que possuem o atributo "price" com valores maiores estarão no começo.
<URI_da_FonteDados>?$orderby=price desc
- Exemplo 2: a requisição abaixo retorna uma lista onde os objetos que possuem o atributo "price" com valores menores estarão no começo. Se não informar a ordem (asc ou desc) o OData reconhece como ascendente.
<URI_da_FonteDados>?$orderby=price
- $select: especifica quais os atributos retornados na lista de objetos.
- Valores aceitos: aceita o nome dos atributos separados por vírgula ",".
- Exemplo: a requisição abaixo retorna uma lista de objetos contendo apenas os atributos "name", "price".
<URI_da_FonteDados>?$select=name,price
- $skip: ignora os primeiros N registros. Ao requisitar $skip=9 em uma coleção de 10 registros, será retornado uma lista com 1 registro, o último.
- Valores aceitos: aceita números inteiros.
- Exemplo: a requisição abaixo retorna uma lista de elementos que começa a partir do elemento 10.
<URI_da_FonteDados>?$skip=9
- $top: a quantidade de registros obtidos pela Fonte de dados será igual ao valor passado por esse parâmetro.
- Valores aceitos: Aceita números inteiros.
- Exemplo: independente da quantidade de registros, a requisição abaixo só retornará uma lista com 5 primeiros registros.
<URI_da_FonteDados>?$top=5
Nesta página
Índice |
---|
Assista sobre o tema no Cronapp Academy
Informações |
---|
Caso seja seu primeiro acesso ao Cronapp Academy, crie antes uma conta gratuita e matricule-se no curso abaixo. |
- Aula: Criar fonte de dados
Nome em inglês
Datasource
Nessa página
Índice |
---|
Compatibilidade
- Formulário web
- Formulário mobile
- Relatório
- Web service
- BPM
Botão do Componente
Image Removed
Imagem no Editor Visual
Image Removed