Usar fórmulas de data, data/hora e hora

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:
  • Descrever quais são os tipos de data, data/hora e hora.
  • Explicar a diferença entre os tipos de data, data/hora e hora.
  • Descrever casos de uso para fórmulas com os tipos de retorno de data, data/hora e hora.
  • Criar uma fórmula usando os tipos de data, data/hora e hora.

Introdução a fórmulas de data, data/hora e hora

Para administrar sua organização, os campos de data e data/hora são ótimos para mostrar a data de nascimento de um contato, a idade de um caso ou a data e hora em que a conta foi criada. Os campos de hora são ótimos para rastrear horários, como o horário do expediente. Você pode usar uma fórmula para exibir a data ou hora atual, ou encontrar a diferença entre duas datas ou horas.

Esta fórmula de objeto cruzado, por exemplo, exibe a data e a hora em que uma conta foi criada como um valor de data/hora na página do caso associado.
Account.CreatedDate

Uma fórmula de objeto cruzado exibe dados de um objeto em um objeto diferente. Neste caso, estamos mostrando CreatedDate (data de criação) do objeto da conta no objeto do caso. Os membros de sua organização podem ver uma fórmula que exibe ou faz referência a um campo de objeto cruzado mesmo que eles não tenham acesso ao objeto em que o campo está. Para obter mais informações sobre fórmulas de objetos cruzados, consulte Dicas para criar fórmulas de objeto cruzado.

Uma data é representada como um valor de data ou data/hora. Um valor de data armazena um ano, um mês e um dia. Um valor de data/hora armazena um ano, um mês, um dia e um horário. A hora é armazenada como GMT, mas é exibida no fuso horário do usuário que a visualiza. É importante pensar nos conflitos de fuso horário enquanto você trabalha com valores de data/hora em fórmulas. Confusões com o fuso horário podem facilmente causar erros lógicos nos campos de fórmula e transmitir informações erradas em sua organização.

Se você está subtraindo dois valores de data, o resultado é um número inteiro. Se você está subtraindo dois valores de data/hora, o resultado é um valor decimal representando o número de dias, horas e minutos. Por exemplo, se a diferença entre dois valores de data/hora é 3,52, há 3 dias, 12 horas (0,5 de um dia) e 29 minutos (0,02 de um dia) entre as duas datas.

Nota

Nota

Um valor de hora armazena as horas, minutos, segundos e milissegundos (HH:MM:SS.MS). Observe que os milissegundos vêm depois de um ponto (.) e não de dois pontos (:). Um valor de hora é como um valor de data/hora sem a data. No entanto, a precisão de um valor de hora é em milissegundos. A precisão de um valor de data/hora é em segundos.

Se você está subtraindo dois valores de hora, o resultado é em milissegundos e é sempre positivo.

TimeField1__c tem o valor 10:00 PM e TimeField2__c tem o valor 9:00 PM:

TimeField1__c - TimeField2__c = 3600000

O resultado nunca é um número negativo. A subtração é o tempo decorrido entre dois valores de tempo, usando um relógio de 24 horas.

Operadores e funções comuns de data, hora e data

O Salesforce oferece várias funções que permitem trabalhar com mais facilidade com valores de data, data/hora e hora. Você pode converter uma data/hora em data usando a função DATEVALUE(), que extrai um valor de data/hora ou texto e retorna uma data. Da mesma forma, DATETIMEVALUE() extrai um valor de data ou texto e retorna um valor de data/hora, com o horário definido como meia-noite GMT. E você pode converter valores de data/hora ou texto em hora usando a função TIMEVALUE().

Digamos que você queira que um campo de fórmula personalizado exiba a data de 17 de março de 2015. Você pode usar a função DATE() para converter um dia, mês e ano no valor de data desejado.
DATE(2015, 03, 17)
DATETIMEVALUE() é outro método para converter texto em um valor de data/hora correspondente a 17 de março de 2015 às 17:00 GMT.
DATETIMEVALUE("2015-03-17 17:00:00")
Você também pode usar DATEVALUE(), que extrai uma string e retorna um valor de data.
DATEVALUE("2015-03-17")
Nota

Nota

DATETIMEVALUE() extrai um valor de data ou texto com o formato AAAA-MM-DD e uma hora em GMT. Se você inserir um valor fora do intervalo válido, como 29 de fevereiro em um ano não bissexto ou um mês acima de 12, o campo de fórmula mostra #Error!

Para localizar o dia atual como um valor de data, use TODAY(). Para localizar a hora atual como um valor de data/hora, use NOW(). Essas funções são úteis para localizar datas no futuro ou no passado, ou saber o intervalo entre o dia de hoje e outra data.

Para extrair apenas o dia, o mês ou o ano de um valor de data como número, use DAY(), MONTH() ou YEAR(), respectivamente.

Os campos de hora usam a função TIMEVALUE() de forma semelhante a DATEVALUE(). Digamos que você queira definir o valor padrão de campo de hora como 5:30 PM. Use o formato de data internacional (ISO) em uma fórmula para o valor padrão do campo.
TIMEVALUE("17:30:00.000")
E para obter a hora atual, use a função TIMENOW(). Também existem as funções HOUR(), MINUTE(), SECONDS() e MILLISECONDS(). Por exemplo, se você estiver rastreando minutos para um temporizador, use TIMENOW() e MINUTE() para obter apenas os minutos da hora atual.
MINUTE(TIMENOW())

Usar os tipos de data, data/hora e hora em fórmulas

Um dos usos mais simples para valores de data é encontrar o número de dias entre duas datas. Quando você subtrai um valor de data de outro, recebe a diferença de dias como um número.

Se você quiser saber quantos dias há entre a data de hoje e a CreatedDate (data de criação) de uma conta, por exemplo, use:
TODAY() - DATEVALUE(CreatedDate)
Nota

Nota

Tenha o cuidado de subtrair apenas datas anteriores de datas futuras. Se você inverter a fórmula (DATEVALUE(CreatedDate) - TODAY()), ela retornará um valor negativo.

Observe que usamos DATEVALUE() para converter CreatedDate, um valor de data/hora, em um valor de data, o que nos permite subtrair CreatedDate de TODAY(). Os valores de data e data/hora não são compatíveis. Não é possível subtrair uma data de uma data/hora, nem uma data/hora de uma data, sem primeiro converter um dos valores.

Você também pode adicionar dias a uma data. Para criar uma fórmula que retorna uma data três dias depois de hoje:

  1. Em Configuração, use a caixa Busca rápida para acessar o Gerenciador de objetos.
  2. Clique em Conta | Campos e relacionamentos e clique em Novo.
  3. Selecione Fórmula e clique em Avançar.
  4. Em Rótulo do campo, insira Data futura. O nome do campo é preenchido automaticamente.
  5. Selecione Data e clique em Avançar.
  6. Insira a seguinte fórmula:
    TODAY() + 3
    Nota Ao adicionar dias a uma data, o Salesforce ignora os números após a vírgula decimal. Então, TODAY() + 3 é equivalente a TODAY + 3.4 e TODAY() + 2 é equivalente a TODAY() + 2.9.

Muito simples, não? As coisas ficam um pouco mais complexas quando você deseja adicionar dias úteis a uma data. Nesta fórmula, usamos a função CASE() para adicionar 3 dias úteis a TODAY(). CASE() é relativamente semelhante a IF(). A principal diferença é que IF() verifica apenas uma declaração lógica, enquanto CASE() verifica uma série de declarações, chamadas de casos.

CASE(expression, case1, result1, case2, result2, ... , else_result) compara expression a case1. Se forem iguais, ela retornará result1. Se não forem, compara expression a case2 e assim por diante. Se a expressão não corresponder a nenhum caso, a declaração retornará else_result.

CASE() é útil para declarações condicionais que têm muitos resultados possíveis. Embora você normalmente possa fazer a mesma coisa com declarações IF() aninhadas, CASE() torna as fórmulas complicadas mais fáceis de ler e entender.

Vamos usar CASE() para escrever uma fórmula que adiciona três dias úteis a HOJE(). A primeira etapa ao trabalhar com CASE() é pensar em casos. Nossa fórmula pode encontrar algumas situações diferentes:

  • Se TODAY() for um domingo, segunda ou terça-feira, adicionar 3 dias úteis é o mesmo que TODAY() + 3.
  • Se TODAY() for uma quarta-feira, quinta-feira ou sexta-feira, adicionar 3 dias úteis é igual a TODAY() + 5 (3 dias úteis e 2 dias do final de semana).
  • Se TODAY() for um sábado, adicionar 3 dias úteis é o mesmo que TODAY() + 4 (3 dias úteis e 1 dia do final de semana).

Para nossa fórmula funcionar, precisamos saber que dia da semana TODAY() é. Use a função WEEKDAY() para encontrar o dia da semana.

Nossa declaração CASE(), então, define um resultado com base no dia da semana de TODAY(). A fórmula final tem esta aparência:
CASE(
  WEEKDAY(TODAY()),
  3, TODAY() + 2 + 3,
  4, TODAY() + 2 + 3,
  5, TODAY() + 2 + 3,
  6, TODAY() + 1 + 3,
  TODAY() + 3
)

Você pode usar variações dessa fórmula para adicionar qualquer número de dias úteis a uma data. Não importa quantos dias úteis você está adicionando, há no máximo sete casos, um para cada dia da semana.

Também é possível realizar operações matemáticas em valores de hora.

A unidade para adicionar ou subtrair valores de hora é o milissegundo.

Quando Timefield1__c tiver o valor 5:00 PM:

  • Timefield1__c + 600000 é 5:10 PM
  • Timefield1__c - 600000 é 4:50 PM

Os campos de hora não incluem uma data. Assim, adicionar 25 horas a um valor de hora é o mesmo que adicionar 1 hora. O relógio é reiniciado após 24 horas.

Lembre-se: como você pode subtrair um campo de hora de outro em uma fórmula, o resultado é em milissegundos e o resultado nunca é um número negativo.

Por exemplo, ao calcular o número de horas em que uma empresa está aberta, você usa a fórmula a seguir.
(ClosedTime - OpenTime) / 3600000

E, para os seguintes horários, você receberá os seguintes resultados.

ClosedTime = 17:00 AM, OpenTime = 8:00 AM, ClosedTime - OpenTime é igual a 9 horas.

ClosedTime = 05:00 AM, OpenTime = 07:00 AM, ClosedTime - OpenTime é igual a 22 horas.

Também é possível configurar regras de validação baseadas em tempo. A fórmula a seguir confere se um turno dura pelo menos 4 horas.
Shift_Ends_Time__c <= (Shift_Start_Time__c + 14400000) 

Exemplos de data, data/hora e hora

  1. Esta fórmula localiza o último dia do mês ao subtrair um dia do primeiro dia do mês seguinte. Ela usa a função ADDMONTHS() para calcular cada mês seguinte antes da subtração.
    DATE(YEAR(ADDMONTHS(Date__c,1)), MONTH(ADDMONTHS(Date__c,1)), 1) - 1
  2. Esta fórmula encontra o número de dias úteis entre TODAY() (hoje) e Date__c antes de hoje. Primeiro, a fórmula encontra o número de dias úteis entre TODAY() e uma segunda-feira conhecida no passado, neste caso, 8 de janeiro de 1900. Dividimos esse número por 7 e usamos FLOOR() para convertê-lo de dias a semanas. Em seguida, ele é multiplicado por 5 para ser convertido de semanas para dias úteis. A fórmula encontra a diferença entre esse valor e o número de dias úteis desde o Date__c e a mesma segunda-feira de referência. O resultado é o número de dias úteis entre TODAY() e um Date__c passado.
    (5 * (FLOOR((TODAY() - DATE(1900, 1, 8)) / 7)) + MIN(5, MOD(TODAY() - DATE(1900, 1, 8), 7)))
    -
    (5 * (FLOOR((Date__c - DATE(1900, 1, 8)) / 7)) + MIN(5, MOD(Date__c - DATE(1900, 1, 8), 7 )))
  3. Esta fórmula adiciona Num_Years__c a Date__c. Ela usa ADDMONTHS(), que processa automaticamente os anos bissextos. Nota ADDMONTHS() considera o último dia de um mês ao realizar operações matemáticas. Assim, quando você adiciona um mês a determinado dia 30 que seja o último dia do mês, o resultado é o último dia do mês seguinte. O valor resultante pode ser o dia 31. Da mesma forma, 28 de fevereiro (em um ano não bissexto) mais um mês é 31 de março.
    ADDMONTHS(Date__c, Num_Years__c * 12)
  4. Em casos, esta fórmula verifica se os representantes estão chamando os clientes na hora preferencial. O campo de hora preferencial representa a hora em que um contato especificou que prefere ser contatado para os casos externos.
    IF(
      IF((HOUR(TIMEVALUE(CreatedDate)) - 7) < 0,
        24 + (HOUR(TIMEVALUE(CreatedDate)) -7),
        (HOUR(TIMEVALUE(CreatedDate)) - 7))
    = HOUR(Contact.Preferred_Time__c), TRUE, FALSE)

Erros comuns em fórmulas de data, data/hora e hora

  • Conversão entre data, data/hora e hora. Os tipos de dados data, data/hora e hora não são intercambiáveis. Se for escrita para retornar um valor de data/hora, uma fórmula com o tipo de retorno data não funcionará. Para converter entre data, data/hora e hora, use as funções internas DATEVALUE(), DATETIMEVALUE() e TIMEVALUE(). Lembre-se de que TODAY() retorna a data atual como um valor de data, enquanto NOW() retorna a data e a hora atuais como um valor de data/hora. E TIMENOW() retorna a data e a hora atuais como um valor de hora.
  • Trabalhar com fusos horários. Os valores de data, data/hora e hora sempre são exibidos no fuso horário do usuário que os visualiza. Os valores de data/hora são convertidos e armazenados como GMT quando um registro é salvo; depois, são convertidos novamente quando um usuário fora do GMT os visualiza. Quando você converte uma data em data/hora, a hora é sempre meia-noite GMT. Não se esqueça de considerar os fusos horários ao converter um valor de data/hora com TEXT(). Quando você converte uma data/hora em texto, ela retorna o horário em GMT, indicado por um Z no final do valor. TEXT() sempre gera um valor de texto com a hora em GMT, não o fuso horário de sua organização. Os valores de hora não estão associados a nenhuma localidade ou fuso horário e não são convertidos entre usuários de fusos horários diferentes. Quando você converte uma data/hora para hora usando TIMEVALUE(), o valor em GMT é retornado.
  • Anos bissextos e datas inválidas. Ao converter texto em valores de data ou data/hora, ou adicionar anos, meses ou dias a uma data ou data/hora, verifique se o resultado ainda é uma data válida. Por exemplo, se sua fórmula tiver o resultado 31 de junho de 2015, o campo de fórmula exibirá #Error! Da mesma forma, se sua fórmula retornar 29 de fevereiro de 2013 (um ano não bissexto), o campo exibirá um erro. Certifique-se de que suas fórmulas representam os anos bissextos e as diferentes durações dos meses.