Timezone Conversion for Users
Displaying the source data in dashboards and visualizations in the timezone of individual users instead of the default timezone stored at the source. Additionally, you can convert a TIME
field to a custom timezone.
User.timeZone
may cause a conflict if you used this as a custom attribute. See Upgrade Workflow.
The functionality is available in the following data sources and for the data stored in the UTC timezone:
- MS SQL
- Snowflake
- MongoDB
- BigQuery
- Hive
- SparkSQL
- Impala
- PostgreSQL
- Redshift
Enable TIME
Conversion To User Timezones
Before you convert a TIME
field for use by users, define their timezone in user regional settings. Next, convert the TIME
field in the source.
Define a User's Timezone
-
Log in as an administrator or a user who has been assigned to a group with user management privileges.
If the user name you log in with is also associated with other Composer accounts, verify that the correct account is selected. See Switch Tenant Accounts.
Select Users and Groups on the UI menu (
). The Users and Groups page work area opens.
Select Users to see a list of all the user definitions that have been defined for the account.
Select a user, then select the Regional Settings tab.
Select the Time Zone for the user from the options available in the drop-down selector.
Select Save to save the user definition.
Convert a TIME
Field of a Source
When you convert field, your software creates a derived field that includes the User.timeZone
system attribute used as an interpolated value, for example to_timezone(TIME_field, '${User.timeZone|UTC}'))
. Use the created derived field in dashboards and visualizations. The data will be recalculated using the account of each individual user with the custom timezone.
Log in as a user with the Administer Sources privilege, or a user with read and write permission for the data source.
Select a source to open it, then select a time field in the Fields tab.
Select the Settingssidebar menu, then select Convert and the Convert to User Timezone option to convert the data type. A field conversion modal window opens.
In the Time to Time Zone Conversion work area, define a Label for the newly created field, then select User Time Zone for the Time Zone field if not already selected.
Select Save to create the new field.
Alternative: Convert a Timezone Once Using a Function
You can convert a field with the TIME
data type into a selected timezone manually using the to_timezone
function. Specify the function as shown below to return static timezone conversion.
Syntax | Example | Use Case |
---|---|---|
to_timezone(TIME_field, 'IANA timezone identifier') |
to_timezone(TIME_field, 'Europe/Kyiv') |
Converts a field |
TIME
fields stored in the UTC timezone at the data source. Conversions performed on the data stored in a custom timezone may be inaccurate.
Upgrade Workflow
If you are upgrading from an earlier version of Composer, this may be a breaking change: the introduction of the system attribute User.timeZone
may cause a conflict if you used this as a custom attribute.
When you upgrade to the latest version of Composer this feature triggers the following changes:
Custom user attributes you manually created with the name the
User.timeZone
in earlier Composer versions (23.2 and earlier) are automatically converted to the system attributes if their value corresponds to the IANA timezone standard ISO 8601 (for example,‘Europe/Kyiv’, ‘UTC+5’
).All custom user attributes
User.timeZone
that do not correspond to the IANA timezone standard are removed.
To ensure a smooth upgrade process, select an upgrade workflow ahead of updating Composer depending on your needs:
If you want to start using your custom attribute
User.timeZone
for timezone conversion purposes, the attribute will be automatically changed to the system value at upgrade. To ensure this takes place, verify before upgrade that the values of the attribute are provided in IANA format before you upgrade Composer.If you want to preserve your custom attribute for other purposes, we recommend renaming the attribute before you upgrade Composer. For example, change
User.timeZone
toUser.timeZone_custom
. Don't change the value of the attributes before running the upgrade script.
API Changes
The APIs in /api/users
has been expanded to include the "timeZone": "string"
parameter. This displays the user's timezone formatted as an IANA timzeone identifier, ISO 8601 (for example, "Europe/Kyiv"). The default value is UTC
.
User.timeZone
is now a reserved system attribute to support this feature. See Upgrade Workflow for alternative approaches.
Comments
0 comments
Please sign in to leave a comment.