Usando valores de data, de data/hora e de hora em fórmulas
As fórmulas de data são úteis para o gerenciamento de prazos de pagamento, idades de contratos ou quaisquer outros recursos de sua organização que dependem de data ou hora.
Edições obrigatórias
| Disponível em: Salesforce Classic e Lightning Experience |
| Disponível em: Todas as edições |
São usados dois tipos de dados para trabalhar com datas: Data e Data/hora. Um tipo de dados, Hora, é independente da data para rastrear o horário, como horário comercial. A maioria dos valores usados ao trabalhar com datas é do tipo de dados Data, que armazena o ano, mês e dia. Alguns campos, como CreatedDate, são campos de Data/hora, o que significa que não só armazenam um valor de data, mas também um valor de hora (armazenado em GMT, mas exibido no fuso horário dos usuários). Os campos Data, Data/hora e Hora são formatados na localidade do usuário quando exibidos em relatórios e páginas de detalhes do registro. A precisão de um valor de Hora é de milésimos de segundos. A precisão de um valor de Data/Hora é de segundos.
É possível usar operações como adição e subtração nos valores de Data, Data/hora e Hora para calcular uma data futura ou o tempo decorrido entre duas datas ou horas. Se uma data for subtraída da outra, por exemplo, o valor resultante será a diferença entre os dois valores iniciais em dias (tipo de dados Número). A mesma operação entre dois valores de Data/hora retorna um valor decimal que indica a diferença no número de dias, horas e minutos. A mesma operação entre dois valores de Hora retorna milissegundo
Por exemplo, se a diferença entre os dois valores de Data/hora for de 5,52, isso significa que os dois valores são separados por cinco dias, 12 horas (0,5 de um dia) e 28 minutos (0,02 de um dia). Também é possível adicionar valores numéricos a Datas e Datas/horas. Por exemplo, a operação TODAY() + 3 retorna três dias após a data de hoje. Para obter mais informações e exemplos de como trabalhar com datas, consulte a lista Exemplos de fórmulas de data.
Ao longo dos exemplos, as variáveis date e date/time são usadas no lugar de campos ou valores reais de Data e Data/hora.
Tenha em mente que as funções de data complexas tendem a compilar em tamanho maior do que funções de fórmula de texto ou número, de modo que possa haver problemas com o tamanho de compilação da fórmula.
TODAY(), NOW() e TIMENOW()
A função TODAY() retorna o dia, mês e ano atuais como tipo de dados Data. Essa função é útil para fórmulas em que você está preocupado com quantos dias se passaram desde a data anterior, a data de determinado número de dias no futuro ou se você simplesmente quiser exibir a data atual.
A função NOW() retorna o valor Data/hora do momento atual. É útil quando você está preocupado com horários específicos do dia e com a data.
A função TIMENOW() retorna um valor em GMT que representa o horário atual sem a data. Quando quiser o valor atual de horas, minutos, segundos ou milissegundos, use esta função em vez da função NOW(). Este valor é útil para controlar períodos como turnos de trabalho ou tempo decorrido.
Para obter mais detalhes sobre como converter entre valores de Data e de Data/hora, consulte Convertendo entre Data/hora e Data.
Função DATE()
A função DATE() retorna um valor Data, fornecendo ano, mês e dia. Os valores numéricos de Y/M/D e as funções YEAR(), MONTH() e DAY() são parâmetros válidos para DATE(). Por exemplo, DATE( 2013, 6, 1 ) retorna 1o de junho de 2013. Da mesma forma, DATE( YEAR( TODAY() ), MONTH( TODAY() ) + 3, 1) retorna o valor de Data do primeiro dia três meses a partir de hoje no ano atual, presumindo que a data seja válida (por exemplo, o mês cai entre 1 e 12).
Se os valores de Y/M/D inseridos resultarem em uma data inválida, a função DATE() retornará um erro, então, é muito importante fazer a verificação de erros como parte do trabalho com valores de data. Os métodos para lidar com datas inválidas são descritos em Exemplos de fórmulas de data.
Convertendo entre Data/hora e Data
Data/hora e Data não são tipos de dados intercambiáveis. Assim, se deseja executar operações entre valores de Data/hora e Data, precisará convertê-los para que sejam ambos do mesmo tipo. Algumas funções (como YEAR(), MONTH() e DAY()) também funcionam apenas com valores de Data, então, os valores de Data/hora precisam ser convertidos primeiro.
Use a função DATEVALUE( date/time
) para retornar o valor de data para Data/hora. Por exemplo, para obter o ano de uma Data/hora, use YEAR( DATEVALUE(
date/time ) ) ).
Se uma fórmula fizer referência a um campo de Data/hora, mas retornar uma Data, o componente de hora será ignorado sem ser convertido no fuso horário do usuário. Esse comportamento pode resultar em uma data incorreta. Para corrigir o fuso horário do usuário, use a função DATEVALUE() para converter o campo Data/hora.
É possível converter um valor de Data para Data/hora utilizando a função DATETIMEVALUE( date ). A hora será ajustada para 0h na Hora de Greenwich (GMT) e depois convertida para o fuso horário do usuário que exibe o registro quando este for exibido. Para um usuário localizado em San Francisco, DATETIMEVALUE( TODAY() ) retorna 17h do dia anterior (no horário de verão) em vez de meia-noite do dia atual. Consulte Uma nota sobre data/hora e fusos horários para encontrar mais informações
Convertendo entre Data/hora e Hora
A função TIMEVALUE() retorna um valor do tipo de dados Hora no formato "HH:MM:SS.MS" (horas:minutos:segundos.milissegundos), usando um relógio de 24 horas. Os valores numéricos H/M/S/MS e as funções HOUR(), MINUTE(), SECONDS() e MILLISECONDS() são parâmetros válidos para TIMEVALUE().
Use a função TIMEVALUE(value) para retornar o valor de Hora de um tipo de Data/hora, texto, campo de mesclagem ou expressão. Por exemplo, extraia a hora do valor de Data/hora ClosedDate com TIMEVALUE(ClosedDate).
Convertendo entre data e texto
Se você quiser incluir uma data como parte de uma string, coloque o valor de Data na função TEXT() para convertê-lo em texto. Por exemplo, se você quiser retornar a data de hoje como texto, use:
"Today's date is " & TEXT( TODAY() )Isso retorna a data no formato “AAAA-MM-DD” em vez de no formato dependente da localidade. É possível alterar o formato primeiro extraindo o dia, mês e ano da data e, em seguida, recombinando-os no formato desejado. Por exemplo:
"Today's date is " & TEXT( MONTH( date ) ) & "/" & TEXT( DAY( date ) ) & "/" & TEXT( YEAR( date ) ) ) Também é possível converter texto em Data para poder usar o valor de string com seus outros campos de Data e fórmulas. Você quer que seu texto seja formatado como “AAAA-MM-DD”. Use essa fórmula para retornar o valor de Data:
DATEVALUE( "YYYY-MM-DD" )Convertendo entre Data/hora e texto
É possível incluir valores de Data/hora em uma string usando a função TEXT(), mas é preciso ter cuidado com os fusos horários. Por exemplo, considere esta fórmula:
"The current date and time is " & TEXT( NOW() )Nesta fórmula, NOW() está deslocado em relação ao GMT. Normalmente, NOW() seria convertido para o fuso horário do usuário quando exibido, mas como foi transformado em texto, a conversão não acontecerá. Então, se você executar essa fórmula em 1º de agosto às 17h na hora de San Francisco (GMT-7), o resultado será “A data e hora atual é 2013–08–02 00:00:00Z”.
Ao converter uma Data/hora em texto, um “Z” é incluído no fim para indicar GMT. TEXT( date/time ) retorna "Z" se o campo estiver em branco. Assim, se o valor de Data/hora no qual você está trabalhando pode ficar em branco, verifique isso antes de converter em texto:
IF(
ISBLANK( date/time ),
"",
TEXT( date/time )
)Para converter uma string em um valor de Data/hora, use DATETIMEVALUE() passando uma string no formato "AAAA-MM-DD HH:MM:SS". Esse método retorna o valor de Data/hora em GMT.
Convertendo entre Hora e Texto
Se você quiser incluir a hora como parte de uma string, coloque o valor de Hora na função TEXT() para convertê-lo em texto. Por exemplo, se você quiser retornar a hora atual como texto, use:
"The time is " & TEXT( TIMENOW() )Esta função retorna a hora no formato "HH:MM:SS.MS".
Também é possível converter texto no tipo de dados Hora, para poder usar o valor de string com seus outros campos de Hora e fórmulas. Formate o texto como "HH:MM:SS.MS" em um relógio de 24 horas. Use a função TIMEVALUE():
TIMEVALUE("17:30:45.125")Observação sobre data/hora e fusos horários
Os valores de Data/hora e Data são armazenados em GMT. Quando um registro é salvo, os valores de campo são ajustados a partir do fuso horário do usuário para GMT e, em seguida, ajustados de volta para o fuso horário do espectador quando exibidos em páginas de detalhes de registro e relatórios. Com conversões de Data isso não representa problema, visto que a conversão de Data/hora para Data resulta no mesmo valor de Data.
Ao trabalhar com campos e valores de Data/hora, porém, a conversão sempre é feita em GMT, não no fuso horário do usuário. Subtrair um campo de Data/hora padrão de outro não é um problema, porque os dois campos estão no mesmo fuso horário. Quando um dos valores no cálculo é uma conversão de um valor de Texto ou Data para um valor de Data/hora, no entanto, os resultados são diferentes.
Digamos que um usuário de San Francisco insere um valor de 0h em 2 de agosto de 2013 em um campo de Data/hora personalizado chamado Date_Time_c. Esse valor é armazenado como 2013–08–02 07:00:00Z, porque a diferença da hora de verão no Pacífico é de GMT-7. Ao meio-dia de 1º de agosto, o usuário exibe o registro e a seguinte fórmula é executada:
Date_Time_c - NOW()No cálculo, NOW() é 2013–08–01 19:00:00Z e, então, é subtraído de 2013–08–02 07:00:00Z, para retornar o resultado esperado de 0,5 (12 horas).
Suponhamos que, em vez de NOW(), a fórmula converta a string “2013–08–01 12:00:00” em um valor de Data/hora:
Date_Time_c - DATETIMEVALUE( "2013-08-01 12:00:00" )Nesse caso, DATETIMEVALUE(
“2013–08–01 12:00:00” ) é 2013–08–01 12:00:00Z e retorna um resultado de 0,79167, ou 19 horas.
Não há como determinar o fuso horário de um usuário em uma fórmula. Se todos os usuários estiverem no mesmo fuso horário, você poderá ajustar a diferença de fuso horário somando ou subtraindo a diferença horária entre o fuso horário dos usuários e GMT para seus valores convertidos. No entanto, visto que os fusos horários podem ser afetados pelo horário de verão e as datas de início e fim do horário de verão são diferentes a cada ano, isso é difícil de gerenciar em uma fórmula. Recomendamos usar Apex para transações que exigem a conversão entre valores de Data/hora e de Texto ou Data.