Função

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

Tipos

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

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

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

Uso

No Editor de Views, os componentes que necessitam de uma fonte de dados possuem uma propriedade chamada Origem dos dados (destaque 4 da figura 1.1) ou Configurações onde é possível selecionar um componente visual fonte de dados já existente na tela ou criar um novo. 

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

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

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

Acesso as propriedades

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

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

Principais propriedades

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

Aba de Estilos

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

Filtros e Parâmetros

A janela de Filtros e Parâmetros permite definir valores para os parâmetros configurados na aba Filtro da Fonte de dados ou adicionar grupos de regras que podem ser relacionados usando conectivos lógicos (e / ou). Regras e parâmetros podem ser configuradas usando expressões, campos da tela, conteúdo estático ou blocos de programação (Figura 2.1).

Figura 2.1 - Janela de Filtros e Parâmetros

1. Parâmetros: os parâmetros exibidos nessa área serão os mesmos configurados na aba Filtro, independente do tipo da Fonte de dados: Bloco de Programação, Entidade ou WebService.
2. Lista dos parâmetros da fonte de dados.
3. Esse campo exibirá sempre o valor de igualdade.
4. Seleciona o tipo do que será comparado: expressão, booleano, String e outros.
5. Valor do parâmetro.
6. 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 5.
7. Exclui a configuração do parâmetro.
8. Configuração do Grupo: define o condicional entre suas regras e outros grupos.
9. Campo de seleção de condicional (e / ou) do grupo.
10. Adiciona nova regra a esse grupo.
11. Adiciona novo grupo filho.
12. Exclui grupo (não é possível excluir o primeiro grupo da hierarquia).
13. Configuração da Regra: define um elemento de comparação entre um atributo da fonte de dados e outro elemento.
14. Seleciona o atributo da fonte de dados.
15. Seleciona o operador de comparação (=; ≠; <; >; <= ou >=).
16. Seleciona o tipo do que será comparado: expressão, booleano, String e outros.
17. Campo para informar o que será comparado: expressões, data, String, bloco de programação ou outros.
18. 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 17.
19. 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.

O mestre-detalhe também dá suporte a manipulação de dados, ao inserir ou atualizar toda a hierarquia do mestre detalhe (pai, filho e demais), salvando ou editando, as informações serão enviadas em uma única requisição. Por exemplo, em uma estrutura com 3 entidades (país, estado e cidade), em vez de salvar o país, depois o estado e por último a cidade, tudo será enviado e salvo de uma única vez. Isso é feito para garantir a unicidade da manipulação de um único formulário do mestre-detalhe.

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

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

Origem dos Dados

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

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

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

1. Coluna nome: separa em níveis as fontes de dados por seus tipos (Bloco de programação, Classe, Entidade, Web Services). 
2. Coluna Tipo: informa se o item é uma fonte de dados ou entidade.
3. Coluna Erro: quando uma fonte de dados possui algum erro de configuração, um ícone de alerta é exibido. Posicione o cursor do mouse sobre o ícone para exibir um tooltip com informações do problema.
4. Coluna Editar: abre a janela de edição da fonte de dados.
5. Manter compatibilidade com Cronapp 1.0: item destinado a manter a compatibilidade dos projetos criados na versão 1.0 do Cronapp com a versão atual.

Configurações

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

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

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

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

1. Ícone Fonte de dados: abre a janela "Buscar Fonte de Dados" onde é possível criar, editar ou excluir fontes de dados.
2. Diretório Fontes de Dados: exibe as fontes de dados do sistema.
   • No menu lateral são listadas as fontes de dados. Dê um duplo clique para editar um datasource ou selecione no menu de contexto "Novo > Fonte de Dados" para criar um.
   • Na janela de seleção as fontes de dados são organizadas pelo tipo da fonte de dados (Bloco de programação, Entidade ou Web Services).
3. Diretório: utilizado para agrupar fontes de dados. Se existir duas fontes de dados de tipos diferentes no mesmo diretório, esse diretório aparecerá vinculado aos 2 filtros de tipos.
4. Fonte de dados: 
   • No menu lateral cada fonte de dados terá o ícone do que o alimenta: Bloco de programação, Entidade ou Web services.
   • Na janela de seleção o ícone das fontes de dados será sempre o mesmo.
5. Informações: ao expandir a fonte de dados na janela, é possível visualizar o que alimenta a fonte de dados (nome do bloco ou endereço REST) e informações de erros na configuração da fonte de dados. 
6. Erro: quando uma fonte de dados possui algum erro de configuração, um ícone de alerta é exibido. Posicione o cursor do mouse sobre o ícone para exibir um tooltip com informações do problema.
7. Editar: abre a janela de edição da fonte de dados.
8. Excluir: apaga a fonte de dados selecionada.

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

Edição da Fonte de dados

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

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

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

Edição em Web Services

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

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

A janela de Obter campos do serviço possui 5 passos para um serviço REST e 3 passos para serviços SOAP. Veja abaixo o objetivo de cada etapa:

• Etapa 1: possui o campo URL para informar o endpoint da requisição e os cabeçalhos necessários para a requisição. Caso a API necessite de autenticação para obter os dados (Verbo Get), como por exemplo, uso do cabeçalho authorization ou x-auth-token, será necessário configurar previamente o campo na aba Cabeçalhos para então executar esse passo e informar o token no novo campo.
• Etapa 2: (Figura 3.2.2) exibe o resultado obtido a partir do endpoint e tentará preencher automaticamente os campos a seguir:
  • Para Obter: caminho JSON (JSON Path) da lista de objetos nas requisições REST ou método que retornará a lista de objetos nas requisições SOAP.
  • Para Contar: usado para gerar a paginação dos registros, espera receber o caminho JSON (JSON Path) do atributo que informa o número total de registros nas requisições REST ou método que informa o número total de registros nas requisições SOAP.
• Etapa 3: apresenta o modelo de um objeto a partir das definições da etapa 2 e tentará inferir automaticamente o campo de Chaves do objeto. Se o endpoint for uma requisição SOAP, essa será a última janela, e após clicar em "Avançar", será direcionado para a aba Campos. 
  • Contagem: exibe o total de registros informado no atributo (REST) ou método (SOAP) "Para Contar" da etapa 2. 
  • Chaves: a fonte de dados tentará identificar o campo chave do objeto, porém, caso o objeto tenha chave composta ou possua um campo chave com nome incomum, clique no campo para expandir a lista de atributos do objeto e selecionar o(s) campo(s) chave(s).
• Etapa 4: lista os campos identificados até essa etapa, é possível informar um novo campo não identificado pela funcionalidade e informar o seu caminho através do JSON Path. Também é possível excluir um campo que julgue desnecessário.
• Etapa 5: lista os campos identificados após as etapas anteriores. Após clicar em "Avançar", o usuário será direcionado para a aba Campos.

Todas as configurações feitas nessas etapas podem ser editadas posteriormente na aba Campos. 

Obter campos do serviço sem metadados

Ao clicar no botão "play" (destaque da figura 3.2.2) utilizando o endpoint de um serviço externo, o Cronapp irá identificar os campos dos objetos retornados e inferir quais os tipos dos campo (exemplo: String, Boolean, Date, ...), porém, nem sempre isso é possível, nesses casos, o desenvolvedor pode completar os passos da janela de Obter campos do serviço e depois acessar a aba Campos (Figura 3.2.3) para configurar manualmente os campos incorretos.

Figura 3.2.2 - Identificando os registros e seus campos

Após avançar e finalizar os passos (Figura 3.2.2), a aba Campos exibirá todos os campos obtidos (Figura 3.2.3). Nesse momento é importante verificar se os tipos, as opções Chaves (Primary keys) e Permite Nulo estão corretos.

Figura 3.2.3 - Campos obtidos automaticamente através a janela Obter campos do serviço

Obter campos do serviço com metadados

Caso o endpoint seja de uma fonte de dados (OData) em um outro projeto Cronapp, e este projeto estiver com a opção Expor Metadados habilitada (aba Configurações do Projeto na Janela de Configurações do Projeto), ao tentar obter o recurso web services, a janela Obter campos do serviço conseguirá obter os metadados do projeto que serve, e com isso, as informações dos campos, como os tipos, se permitem nulo, campos chaves e o campo ObjectKey.

Figura 3.2.4 - Obtendo os campos de um serviço OData (Fonte de dados) com os metadados expostos

Após avançar e finalizar os passos (Figura 3.2.4), a aba Campos exibirá todos os campos obtidos (Figura 3.2.3) exatamente como foi configurado no Diagrama de dados do projeto que gera o serviço.

Figura 3.2.4 - Campos obtidos a partir de um serviço (OData) com os metadados expostos

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 da função do bloco de programação vinculado a fonte de dados, esses parâmetros podem ser configurados logo abaixo (destaque 3 da figura 3.3).
• Web Services - REST: os filtros são definidos através das configurações dos parâmetros na aba Ações. Cada verbo da aba Ações (Para obter, Para inserir, ...) permite configurar novos parâmetros e escolher como serão alimentados, caso escolha a opção "Parâmetro" na coluna Valor do campo e informar um nome, esse parâmetro será exibido na lista de parâmetros da aba Filtro (destaque 3 da figura 3.3).
• Web Services - SOAP: aqui os filtros são definidos através dos parâmetros dos métodos selecionados na aba Ações. Cada verbo da aba Ações (Para obter, Para inserir, ...) permite selecionar um dos métodos presentes no recurso SOAP, caso o método escolhido possua parâmetros e, nas configurações do verbo, for escolhido a opção "Parâmetro" na coluna Valor do campo e informado um nome, esse parâmetro será exibido na lista de parâmetros da aba Filtro (destaque 3 da figura 3.3).

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

Figura 3.3 - Exemplo de filtro para uma entidade

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

Ações

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

Fontes de dados do tipo Bloco de programação que possuam uma entidade vinculada no campo Entidade base exibirão também a opção "Padrão" na caixa de seleção das 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 das funções contida no bloco de programação (Figura 3.4).

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

1. Coluna Ações: ativa ou desativa cada um dos verbos HTTP.
2. Coluna opção da ação: essa coluna terá um comportamento diferente a depender do tipo da fonte de dados:
   • Entidade: possui um padrão próprio para executar os verbos e não é possível personalizá-los.
   • Bloco de Programação: é possível selecionar apenas funções existentes no arquivo do bloco de programação (blockly) que alimenta a fonte de dados. Essas funções devem receber por parâmetro o objeto da entidade.
   • Web Services (Rest): é possível definir um endpoint específico para cada ação e adicionar novos parâmetros para essa requisição (ver mais em Ações em Web Services).
   • Web Services (SOAP): é possível selecionar qualquer um dos métodos do serviço SOAP e definir os parâmetros desse método (ver mais em Ações em Web Services).
3. "…": esse botão ficará habilitado apenas em fontes de dados do tipo Web Services e abre uma janela para personalizar os parâmetros do método SOAP ou endpoint REST em cada ação.

4. Permissão: define quais permissionáveis podem executar esses verbos.
   

   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 (destaque 11 da figura 3.6) configurados automaticamente para "Administradores".

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).

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

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

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

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

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

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

Parâmetros REST

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

Query String

No formato Questy Stirng, após o endereço do endpoint é adicionado o caractere ? (interrogação) para informar onde começa a lista com os parâmetros (Chave=Valor), e entre cada parâmetro (Chave=Valor ) é adicionado o caractere & (ampersand),

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

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

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

Rotas

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

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

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

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

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

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

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

Alterar endpoint via parâmetro do sistema

Em situações onde temos diversas fontes de dados que obtém recursos de um mesmo domínio e esse domínio pode mudar de endereço, gerando um novo endpoint, é possível utilizar a funcionalidade Parâmetros do Sistema para alterar todos os domínios de uma só vez. Esse mesmo recurso pode ser utilizado também para alterar as rotas do endpoint.

Acessar a funcionalidade Parâmetros do Sistema e informe o nome do parâmetro e o seu valor (domínio ou rota) (Figura 3.4.6).

Figura 3.4.6 - Janela de configurações dos Parâmetros do sistema

Na janela de configurações da Fonte de dados podemos substituir o domínio (ou rota) do endpoint pelo parâmetro criado, utilizando os caracteres ${} em volta, exemplo: ${dominioAPI} (destaque 1 da figura 3.4.7). Ao executar o web services para obter os campos (destaque 2), o Cronapp montará o endpoint com base no parâmetro configurado (3). 

Figura 3.4.7 - Utilizando o parâmetro do sistema para alterar o endpoint da requisição

Eventos

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

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

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

Colunas

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

Eventos

• Antes de Inserir:  realiza o evento antes da inserir de algum dado.
• Depois de Inserir: realiza o evento após a inserir de algum dado.
• Antes de Deletar: realiza o evento antes de deletar algum dado.
• Depois de Deletar: realiza o evento após deletar algum dado.
• Antes de Atualizar: realiza o evento antes da atualizar de algum dado.
• Depois de Atualizar: realiza o evento após a atualizar de algum dado.
• Ao navegar: executa a ação ao abrir e ao navegar entre os elementos da fonte.
• Ao 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 URL sem permissão.  Esse evento será executado para todos as chamada GET, PUT, DELETE, POST da fonte de dados. Esse evento pode ser muito útil para sistemas multitenant. 
  
• Ao Gerar Erro: tratamento de erros de qualquer natureza durante o processo de manipulação de dados de uma Fonte de Dados.

Campos

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

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

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

1. Campo a adicionar: nome do campo a ser adicionado. Esse campo não é exibido em fontes de dados do tipo Entidade.
2. Adicionar campo: insere um campo a mais em relação aos da entidade base. Esse botão não é exibido em fontes de dados do tipo Entidade.
3. Nome dos campos: coluna com o nome dos campos.
4. Valor do campo: define o tipo do valor que irá alimentar o campo, podendo ser tipos estáticos (Tipos primitivos), Bloco de programação ou Expressões. Acesse o tópico Parâmetros e constantes para mais detalhes.
5. Conteúdo: permite alimentar o campo utilizando outros recursos. Acesse o tópico Parâmetros e constantes para mais detalhes.
6. Tipo do campo: define o tipo do campo.
7. Permite nulo: define se o campo aceitará valores nulos.
8. Chave: define se o campo é uma das chaves primárias da entidade.
9. Bloco: crie ou selecione uma função de bloco de programação para alimentar o campo.
10. Caminho: disponível apenas para fontes de dados do tipo Web Services, permite informa o caminho (JSON Path) do atributo que irá alimentar o campo (ex,: $.data[0].id). 
11. Permissões: define restrições para cada verbo aos permissionáveis cadastrados no sistema. As configurações das permissões feitas na aba Ações serão herdadas automaticamente para cada atributo. Mesmo após a herança de permissões, é possível ajustar as permissões individualmente em cada atributo.
    
12. Limpar: apaga as configurações feitas no campo.
13. Excluir: exclui o campo.

Campo calculados

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

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

Figura 3.7 - Aba de campos calculados

1. Campo a adicionar: nome do campo a ser adicionado.
2. Adicionar campo: insere o campo calculado.
3. Nome dos campos: coluna com o nome dos campos.
4. Valor do campo: define o tipo do valor que irá alimentar o campo, podendo ser tipos estáticos (Tipos primitivos) ou Expressões. Acesse o tópico Parâmetros e constantes para mais detalhes.
5. Conteúdo: permite alimentar o campo utilizando outros recursos. Acesse o tópico Parâmetros e constantes para mais detalhes.
6. Tipo do campo: define o tipo do campo.
7. Bloco: crie ou selecione uma função de bloco de programação para alimentar o campo.
8. Caminho: opção não disponível para Campos calculados.
9. Permissões: define restrições para cada verbo aos permissionáveis cadastrados no sistema. As configurações das permissões feitas na aba Ações serão herdadas automaticamente para cada atributo. Mesmo após a herança de permissões, é possível ajustar as permissões individualmente em cada atributo.
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.

Cabeçalho de autenticação

Serviços web privados necessitam de algum tipo de autenticação para acessar seus dados, normalmente essa autenticação é feita a partir de um token (exemplo: X-AUTH-TOKEN) que é passado no cabeçalho da requisição. Veja alguns detalhes sobre isso nos tópicos abaixo.

Token ao Obter campos do serviço

Antes de iniciar a janela para Obter campos do serviço, é necessário incluir o campo de autenticação, dessa forma, o campo será exibido na primeira etapa da janela "Obter campos do serviço".

É importante destacar que, mesmo que tenha criado e configurado o campo para obter o token na aba Cabeçalhos (via bloco, expressão "token" ou de forma estática) (destaque 1 da figura 3.9.1), ao abrir a janela Obter campos do serviço será necessário informar o token de forma explícita (destaque 2 da figura 3.9.1). visto que os campos de cabeçalhos na janela "Obter campos do serviço" são efêmeros e tem como único objetivo obter os atributos do objeto do serviço.

Figura 3.9.1 - Mesmo configurando o token na aba Cabeçalhos, é necessário informar o token ao obter os campos do serviço

Autenticação entre projetos Cronapp

Se você possui ao menos 2 projetos Cronapp em que um irá servir recursos REST para os outros, é possível configurar para que ambos projetos possuam o mesmo ID de token, dessa forma, as autenticações REST ocorrerão automaticamente. Essa configuração pode ser feita no campo Token da janela de Configurações do projeto (aba Configurações do projeto). O Campo Token possui o ID que faz referência ao Token em si, dessa forma, ambos projetos farão referência ao mesmo token.

Figura 3.9.2 - Obtendo o ID de token do projeto servidor

O campo Token do projeto Servidor (destaques 1 da figura 3.9.2) pode ser copiado para o mesmo campo nos projetos clientes (destaques 1 da figura 3.9.3).

Figura 3.9.3 - Alterando o ID de token dos projetos clientes para o mesmo ID de token do projeto servidor

Após isso, basta selecionar a constante token (Figura 3.9.4) nos campos de autenticações dos projetos clientes.

Figura 3.9.4 - Autenticando as requisições a partir da constante token

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.10, o campo está com uma chave de internacionalização atendendo dois ou mais idiomas.

Figura 3.10 - 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. Limpar: exclui o conteúdo preenchido no campo.
4. Internacionalização: Abre a janela de internacionalização da mensagem;

Outras informações

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

Tipos de eventos

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

Eventos internos da fonte de dados

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

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

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

Eventos do componente visual Fonte de dados

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

Figura 4.2 - Eventos do componente Fonte de dados

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

Ao mudar de status

Para que um evento possa ocorrer, é necessário associa-lo à um bloco de programação, confira na imagem abaixo um pequeno exemplo para o evento Ao mudar de status. Lembre-se sempre de associar o bloco de programação ao formulário que se deseja associar o evento, no exemplo abaixo estamos utilizando o formulário User.

Figura 4.2.1 - Bloco de programação que será associado ao evento Ao mudar de status

Na figura 4.2.1 estamos indicando que o título da página Usuários será alterado em duas situações diferentes, a primeira é se estivermos adicionando um usuário, o título deixará de ser Usuários e passará a ser Adicionar Usuário, o mesmo ocorre na situação seguinte, se estivermos editando um usuário, o novo título da página será Editar Usuário. Caso nenhuma dessas condições sejam atendidas, o título permanecerá o mesmo. Confira na figura 4.2.2 como adicionar esse bloco ao evento no editor de view.

Figura 4.2.2 - Bloco de programação que sendo associado ao evento Ao mudar de status

1. Inicialmente clique na fonte de dados;
2. Logo em seguida, acesse a aba de Eventos;
3. Na propriedade Ao Mudar de Status, clique no ícone "...";
4. Por fim, na janela que irá surgir após a conclusão do passo 3, clique no ícone "..." e associe o bloco criado.

Lançar exceção

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

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

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

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

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

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

Parâmetros e Constantes

A janela de configurações de parâmetros (Figura 5.1) 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. 

Figura 5.1 - 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 5.1) 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 5.1):

1. Estáticos: possui as seguintes opções: Texto, Numérico, Data e Hora, Hora ou Lógico.
   • Coluna conteúdo: (destaque b da figura 5.1) 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.
2. 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. Veja mais detalhes no tópico Ações em Web Services.
   • Coluna conteúdo: (destaque b da figura 5.1) 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 caractere dois-pontos na frente ":minhaVar". Os parâmetros destacados no item 2 da figura 5.1 possuirão o mesmo resultado.
3. Bloco: permite executar um bloco de programação servidor para retornar um valor. 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 5.1) exibe um campo onde é possível selecionar um bloco de programação Servidor.
4. Expressão: permite selecionar um item da lista de constantes ou criar expressões FTL.
   • Coluna conteúdo: (destaque b da figura 5.1) exibe uma caixa de seleção editável onde é possível selecionar/adicionar uma constante Cronapp ou informar uma expressão FTL.

Expressão

A opção Expressão na coluna Valor do campo (destaque a da figura 5.1) 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 5.1). Esse recurso pode ser bem útil no caso de parâmetros simples, porém, ao necessitar de algo um pouco mais complexo, recomendamos fortemente criar um bloco de programação servidor e executar os cálculos.

Expressões FTL são criadas inserindo o termo "expression:" e os caracteres "${ <conteúdo> }" em cada expressão (destaque 4 da figura 5.1).

expression: ${page - 1}

O resultado da expressão contida no bloco acima será o valor da constante "page" subtraído de 1.

Para fazer conversões simples dentro de expressões FTL, basta incluir "?number" para forçar a conversão do tipo texto para o tipo numérico.

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.

Constantes

As constantes Cronapp permitem retornar um valor especificado, dessa forma, é possível passar esses valores em parâmetros query String ou parâmetros de funções. Alguma dessas constantes também são aceitas dentro de expressões FTL, veja a lista das constantes aceitas no tópico Expressão.

• 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 FTL criada. Exemplos:
  • Na expressão "expression:${1 + 1}" o valor retornado será "2".
• 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 de top e skip.

  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 5+1): 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 5.2) da aba Eventos:

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

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.

É 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