Date Handling in the SoftLayer API

Most of the data presented in the SoftLayer API is date-sensitive. Servers have provision dates, tickets have modify dates, and nearly everything has a creation date. To maintain compliancy and consistency standards for all of our users worldwide, SoftLayer presents its dates in [http://www.iso.org/iso/date_and_time_format ISO 8601] format under the data type dateTime. ISO 8601 represents a complete date including date, time and time zone. Every data type property in the SoftLayer API that ends with the string "Date" is represented by the dateTime format.

The dateTime Datatype

The dateTime data type uses the following format:
<YYYY>-<MM>-<DD>T<HH>:<MM>:<SS>-<TZ>

For example the dateTime value 2007-07-19T15:21:48-05:00 translates to:
July 19, 2007, 3:21:48 P.M., GMT -0500

Refer to the information below for more information regarding the data represented in the dateTime data type:

  • YYYY: A four digit representation of the year
  • MM: A two digit representation of the month, including a leading zero, if applicable. (Acceptable range of 01 to 12)

    Example: February = 02

  • DD: A two digit representation of the day, including a leading zero, if applicable. (Acceptable range of 01 to 31)
  • HH: A two digit representation of the hour in 24-hour format, including a leading zero, if applicable. (Acceptable range of 00 to 23)

    Examples:
    • 1:00 a.m. = 01
    • 1:00 p.m. = 13

  • MM: A two digit representation of the minute, including a leading zero, if applicable. (Acceptable range of 00-59)
  • SS: A two digit representation of the second, including a leading zero, if applicable. (Acceptable range of 00-59)
  • TZ: The time zone, represented as the different between the current time zone and GMT in HH:MM format.

    Example: -05:00 = GMT-0500

Setting Your Time Zone

If your API calls return incorrect times for your location, you likely need to set (or reset) the time zone and/or Daylight Savings Time options for the user making API calls. A user's time zone and Daylight Savings Time options can be reset through the SoftLayer Customer Portal or using a direct API call.

Portal

Follow the steps below to set your user's time zone via the SoftLayer Customer Portal

  1. Access the [http://manage.softlayer.com SoftLayer Customer Portal]
  2. Enter your username in the User name field
  3. Enter your password in the Password field
  4. Click the Administrative link
  5. Click on your username in the User List
  6. Select the desired time zone from the Time Zone drop down list
  7. Determine if Daylight Savings Time should be active for the user
    Note: The system defaults to active Daylight Savings Time return
    • If Daylight Savings Time should be active for the user click the Yes radio button under the Daylight Savings Time option
    • If Daylight Savings Time should be inactive for the user click the No radio button under the Daylight Savings Time option

  8. Click the Edit User Profile button

API

To set your user's time zone using a direct API call, complete the following steps:

  1. Invoke the editObject method in the SoftLayer_User_Customer service
  2. Set the timeZoneId property in the template object passed to the call
    Note: Retrieve a list of time zones from SoftLayer_Locale_Timezone::getAllObjects
  3. Determine if Daylight Savings Time should be active for the user
    Note: The system defaults to an active Daylight Savings Time return
    • If Daylight Savings Time should be active for the user enter 1 under the daylightSavingsTimeFlag property
    • If Daylight Savings Time should be inactive for the user enter 0 under the daylightSavingsTimeFlag property

See Also

SoftLayer_Locale_Timezone
SoftLayer_Hardware_Server::getObject

External Links

[http://www.iso.org/iso/date_and_time_format ISO 8601] at [http://wikipedia.org Wikipedia]