You are here:
Considerations for the Time Custom Field Type
Track time, unbound to a date, with the Time custom field type, which is useful for time management, event planning, and project management.
You can select the Time field type when you create a custom field. The Time type is a timestamp without the date included. A Time field value’s precision is in milliseconds. A date/time field value’s precision is in seconds. Use the time field type when you require a time of day that isn’t specific to a single date. For example, use it to show business hours, or if you want to compare times of day to calculate a duration.
Time Field Behavior
Time field values follow these behaviors.
- In formulas, get a time value from the
TIMEVALUEfunction. UseTIMENOW,HOUR,MINUTE,SECOND, andMILLISECONDfunctions with time in formulas. - The Time field type is represented in Metadata API as a FieldType enumeration value.
- A time field value is saved according to the saving user’s time zone. When the time value is displayed in Salesforce, the value matches what’s saved. It isn’t converted to a user’s local time zone per the user’s Locale setting on the Language & Time Zone page.
- The stored time value is appended with a “Z”, but the time isn’t UTC, it's the time of the saving user's time zone. When you query a time field value using SOQL or the API, disregard the appended “Z.” For example, a user saves the time, which is 7:00 AM in their time zone. When you query the time via SOQL or the API 07:00:00.000Z is returned.
- The time is saved in a 24-hour format. For example, 07:00:00.000Z is 7:00 AM, and 19:00:00.000Z is 7:00 PM.
- The unit for adding or subtracting a time value is milliseconds. For example,
Timefield1__c has the value “5:00pm.”
- Timefield1__c + 600000 is “5:10pm”
- Timefield1__c - 600000 is “4:50pm”
Time fields don’t include a date. So, adding 25 hours to a time value is the same as adding one hour. The clock restarts after 24 hours.
- You can subtract one time field from another in a formula. The result is in
milliseconds. For example, TimeField1__c has the value “10:00pm” and TimeField2__c has the
value “9:00pm”:
- TimeField1__c - TimeField2__c is 3600000
The result is never a negative number. Subtraction is the difference between two time values, using a 24-hour clock. For example, when calculating the number of hours that a business is open, you use this formula:
(ClosedTime - OpenTime) / 3600000.ClosedTime= 5 PM,OpenTime= 8 AM,ClosedTime - OpenTime= 9 hoursClosedTime= 5 AM,OpenTime= 7 AM,ClosedTime - OpenTime= 22 hours
-
In formula expressions, use the international date format (ISO) for text arguments. For example, use TIMEVALUE("11:30:00.000") instead of TIMEVALUE("11:30 AM").
Time Field Limitations
Be aware of these limitations when using a field created from the Time field type. The time field:
- Isn’t supported in Process Builder, and Schema Builder
- Doesn't support the creation of custom index for SOQL queries
- Isn’t available for standard lookup relationships in external objects
Formatting Time Fields in Salesforce Classic
In Salesforce Classic, you have several formatting options when you set a time value. For example, you can set a time value to include seconds, milliseconds, time zone, and use 24-hour notation.
- The time custom field type can use 24-hour notation. You can save a time value in HH:MM, for example, 14:40.
- Time fields support the following input formats.
h= Hour of day (1-12), H = Hour of day (0-23), m= minute, s= seconds, S= milliseconds, a= AM or PM, Z= GMT time zone.Format Example hh:mm:ss aa 10:30:25 AM hh:mm:ss.SSS a 10:30:25.125 AM HH:mm:ss.SSS 14:30:25.125 HH:mm:ss.SSSZ 14:30:25.125Z displays as GMT hh:mm a 10:30 AM hh:mma 10:30AM h a 4 PM ha 4PM H:mm 1:23 is 1:23 AM H 14 is 2:00 PM Hmm 123 is 1:23 AM HHmm 1434 is 2:34 PM - Use the 11:30:00.000Z format when loading values with Data Loader.
- Use the HH:MM:SS.MS format to set a default value for a field, such as
TIMEVALUE("10:30:00.000")for 10:30 AM.
