Campos da Estrutura

Os campos são responsáveis por quais dados farão parte da estrutura.

Criando um novo Campo

Acesse a área administrativa e navegue para área: "Estruturas". Selecione qual estrutura deseja criar um novo campo e navegue para a aba "Campos" na navegação secundária. Clique no botão de mais para criar um novo campo preencha todos os campos e clique em "salvar".

INFO

Lembre-se que ao selecionar o tipo de um campo ele não poderá mais ser alterado. O Tipo é o atributo mais importante, ele define como o dado será armazenado pela plataforma e como o campo será visualmente exibido para o usuário.

O campo de "Código" deve ser preenchido seguindo o padrão de utilizar sempre letras minusculas, sem acentuação, sem utilizar ponto. A melhor prática seria utilizar a convenção de nomenclatura camelCase para definir o valor do código de um campo.

O campo Visualização é utilizado para definir como o campo irá exibir o dado para o Usuário. Essa configuração não altera como o valor será armazenado pela plataforma. Sendo assim é possível mudar a visualização a qualquer momento.

O campo Obrigatório é utilizado para definir que esse valor tem que ser definido desde a criação de uma nova instãncia e nunca pode ser vazio.

INFO

Lembre-se que ao definir um campo como Obrigatório você necessariamente terá que incluir ele na sessão de criação no painel da estrutura. Saiba mais sobre a configuração de painais de estruturas clicando aqui.

O campo Bloqueado é utilizado para definir que esse valor não pode ser editado.

O atributo Auditoria é utilizado para definir se esse campo deve armazenar quem editou, quando editou e para qual valor foi editado.

Os campos Fonte de Dados é obrigatório para os tipos de campos do tipo Seleção e Seleção Multipla é ele quem define quais as opções estarão disponíveis para o usuário. Para mais informações sobre a criação de uma nova fonte de dados clique aqui.

INFO

Quando a fonte de dados é do tipo dinâmico pode ser utilizado o campo Filtro para a fonte de dados para definir qual o filtro deve ser aplicado nos resultados. Nesse campo devemos utilizar a notação de criação de filtros para o banco de dados MongoDB, clique aqui para saber mais.

{ "strucuture": "vendor" }

Configurações Extras

Além das configurações existentes no momento de criação temos outros atributos que podemos definir para o campo.

Os atributos "Regra para definir como bloqueado", "Regra para definir obrigatoriedade" e "Condição para ocultar" são utilizados respectivamente para bloquear a edição, tornar o valor obrigatírio e ocultado o campo da visão do usuário. Para que essas ações sejam realizadas baste definir como valor do campo um código que quando retornar verdadeiro o campo será definido como: bloqueado, obrigatório ou oculto.

INFO

Importante lembrar a ordem de execução das regras de definição de um campo como bloqueado tem uma certa sequencia. No caso a ordem de prioridade é a seguinte:

1. Definição do atributo "readonlyBypass" no campo que faz com que o campo fique aberto para edição;
2. Definição de bloqueio global do campo;
3. Definição da regra de bloqueio no próprio campo;
4. Definição da regra de bloqueio na estrutura do campo;
5. Definição da regra de bloqueio no estrutura pai;

${data.custom.status === "aprovado"}

O atibuto "Dica" é utilizado para definir um texto que pode ser complementar ao rótulo do campo. Ele aparece como um ícone de informação laranja dentro do campo e ao passar o mouse exibe o conteúdo da Dica.

O atibuto "Auxiliar" é utilizado para definir campos que não devem estar disponíveis para os usuários. Campos que são apenas utilziados para gerar dados auxiliares e que provavelmente farão parte de alguma formula mais complexa e que precisa ter dados intermediários calculados.

O atibuto "Valor Padrão" é utilizado para definir um valor que vai estar preenchido no campo quando uma nova instância for criada.

Validaçoes

Podemos criar validaçoes customizadas que serão aplicadas ao atualizar o valor do campo. Para isso devemos definir um código JSON com uma lista de validações que serão aplicadas no campo. Cada validação deve conter obrigatoriamente qual a regra que deve ser atendida e a mensagem caso não seja validada.

Acesse a área administrativa e navegue para área: "Estruturas". Selecione qual estrutura deseja editar o campo e navegue para a aba "Campos" na navegação secundária. Clique no código do campo e preencha o atributo "Validaçoes" de acordo com as configurações a seguir:

Exemplo de um campo de data que não pode ter um valor menor que o dia de hoje

[
  {
    "message": "Não é possível selecionar uma data menor que hoje!",
    "rule": "${pattern.date(hrz.now).isAfter(data.custom.ref)}"
  }
]

Mapeamento de Exibições

Para campos do tipo numérico e data podemos definir um mapeamento de exibições de acordo com o valor.

Acesse a área administrativa e navegue para área: "Estruturas". Selecione qual estrutura deseja editar o campo e navegue para a aba "Campos" na navegação secundária. Clique no código do campo e preencha o atributo "Mapeamento de Exibições" de acordo com as configurações a seguir:

Atributos	Descrição
condition	Define um código que caso verdadeiro aplique a definição
from	Define o valor de partida da faixa
to	Define o valor final da faixa
icon	Define o ícone
valueColor	Define a cor do texto
label__translation	Define o rótulo para a faixa

INFO

Os campos com Mapeamento de Exibições terão um filtro criado para selecionar as faixas que foram criadas e o rótulo de cada faixa será definido pelo atributo "label__translation".

• Exemplo de exibição caso sem o uso de faixas para definir qual será a exibição. Caso a condição seja atendida será aplicada a definição visual.

[
  {
    "condition": "${data.custom?.plan?.value !== data.custom?.bdg?.value}",
    "icon": "mdi-alert",
    "label__translation": {
      "pt": "Desvio"
    },
    "valueColor": "#FF8103"
  }
]

• Exemplo utilizando multiplas condições para definir qual será a exibição visual será aplicada. Nesse caso a ordem das condições é importante já que quando a plataforma encontrar uma condição válida ele para tentar as próximas.

[
  {
    "condition": "${pattern.date(data.custom?.termReal).diff(data.custom?.dataterm,'d') > 45}",
    "icon": "mdi-alert",
    "label__translation": {
      "pt": "Desvio Alto (+45 dias)"
    },
    "valueColor": "#B82940"
  },
  {
    "condition": "${pattern.date(data.custom?.termReal).diff(data.custom?.dataterm,'d') > 30}",
    "icon": "mdi-alert",
    "label__translation": {
      "pt": "Desvio Médio (+30 dias)"
    },
    "valueColor": "#F84941"
  },
  {
    "condition": "${pattern.date(data.custom?.termReal).diff(data.custom?.dataterm,'d') > 15}",
    "icon": "mdi-alert",
    "label__translation": {
      "pt": "Desvio Baixo (+15 dias)"
    },
    "valueColor": "#FF8F41"
  }
]

• Exemplo utilizando faxas de valor para definir qual será a exibição visual será aplicada.

[
  {
    "icon": "mdi-trending-down",
    "label__translation": {
      "pt": "Desvio negativo"
    },
    "to": "-0.1",
    "valueColor": "#c74040"
  },
  {
    "from": "0",
    "icon": "mdi-trending-up",
    "label__translation": {
      "pt": "Desvio positivo"
    },
    "valueColor": "#205591"
  }
]

INFO

Caso seja definido apenas o atributo "from" o sistema entende que deve considerar todos os valores a partir do que foi definido no atributo "from".

O mesmo ocorre se for definido apenas o campo "to" o sistema entende que deve considerar todos os valores até o que foi definido no "to".

Formulas de Cálculo

Um campo do tipo numérico pode ter uma formula que calcula o valor automaticamene de acordo com outros dados da plataforma. Uma formula é composta por 3 blocos separados por colchetes.

O Primeiro bloco define a origem dos dados, o segundo bloco o filtro que deve ser aplicado sobre o resultado do primeiro bloco e o terceiro bloco definie a ação que deve ser executada para gerar o resultado final.

Primeiro Bloco

Para definir o primeiro bloco devemos entender que ele possuí os seguintes elementos internos:

• Origem dos Dados

Define de onde virão os dados que iremos utilizar no terceiro bloco que calcula o resultado final.

Opção	Descrição
self	Define que os dados utilizados estão na instãncia que possui o campo.
fk	Define que iremos utilizar uma referência externa
code	Representa o código da extensão filha associada a estrutura

No caso da opção fk devemos colocar também o código do campo que será utilizado como referência externa.

• Ordem de execução da Formula

Define qual formulá deve ser executada primeiro. Essa funcionalidade deve ser utilizda quando precisamos utilizar um valor processado em outro campo. Vale lembrar que esse atributo é opicional e que as formulas são executadas paralelamente caso não seja especificada uma ordem.

Segundo Bloco

O Segundo Bloco é opicional caso não seja necessário aplicar nenhum filtro sob s dados do Primeiro Bloco.

Quando o primeiro bloco tem a opção "self" o filtro funciona como condições para executar diferentes ações no terceiro bloco.

INFO

Para formulas cuja origem dos dados é self temos disponível duas funções para auxiliar no tratamento e contparação entre datas.

• addDateFunction(date, years, months, days)
• diffDateFunction(date1, date2)

Exemplos:

[custom.percentComplete == 0;custom.percentComplete == 1]
[addDateFunction(custom.start, 0, 0, 15) > hrz.now]
[diffDateFunction(custom.start, custom.finish) > 15]

Já quando o primeiro bloco está definido resultados de extensões ou de estruruas externas (fk e code) esse bloco define filtros para saber quais itens devem fazer parte do resultado para utilização no terceiro bloco. Caso seja necessário incluir multiplos filtros deve ser utilizado ";" como separador.

Os tipos de filtro disponíveis são: $max, $min, $eq, $ne, $gt, $lt, $gte, $lte.

Para definir o bloco de filtro devemos utilizar a seguinte notação:

[tipo_filtro::código_campo:valor:tipo_valor]

Definir o tipo do valor não é obrigatório e sempre que não for definido o sistema vai entender que o valor é um texto. No caso de valores que não sejam texto devemos definir o tipo correto como: date, number ou bool.

INFO

Caso esteja utilizando campo do tipo data no seu filtro e queria comparar com a data atuali basta usar o valor como sendo "now".

Se tiver a necessidade de validar se um campo está vazio devemos utilizar o valor como sendo "__".

Exemplos:

[$max::custom.finish]
[$min::custom.totalEffort]
[$eq::custom.active:true:bool]
[$gt::custom.value:20:number]
[$gt::custom.start:now:date]
[$lte::custom.startAt:now:date]
[$eq::custom.hierarchyCode:__]

Terceiro Bloco

Define qual ação será executada para gerar o resultado final dessa formula. Este bloco suporta expressão aritmética para calcular o resultado a ser salvo no campo onde o formulário está definido.

Exemplos:

[custom.totalTickets*custom.ticketCost.value]
[$sum::custom.effort]
[$avg::custom.score]
[$count]

ATENÇÃO

Lembre-se de quando utilizar a expressão aritmética da divisão de checar se o campo que é o divisor não é zero. Para isso basta utiliar o segundo bloco com um código para validar se o divisor é igual a zero.

Exemplos de Formulas

• Multiplicar dos valores de campos da própria estrutura

[self][custom.totalTickets*custom.ticketCost.value]

• Definir o valor como zero caso o percentual concluído seja 1 e colocar o valor do campo esforço se for difernete de zero.

[self][custom.percComp == 1][0;custom.effort]

• Somar o custo total de todas as instâncias de melhorias, que estão associadas ao campo "melhorias".

[fk::custom.enhancements::2][$sum::custom.cost.value]

• Calcular o total de tarefas existentes

[task][$count]

• Calcular o valor total das medições que estão ativas

[kpi-measurement][$eq::custom.active:true:bool][$sum::custom.value]

• Calcular o percentual baseado na divisão entre o real e o planejado. Utilizar o filtro para evitar uma divisão por zero

[self][custom.totalplan==0][0;custom.totalreal/custom.totalplan]