Best practices of changing your time zone
If you are thinking about changing the time zone of your tenant, this article describes the steps you need to take and what you need to know before changing your time zone.
What steps should I take before changing my time zone?
Before you change your time zone, do the following:
- Ensure that your Zuora integration is using WSDL 69 or later.
- If you choose not to use WSDL 69 or later, ensure that you are not passing in time zone offsets to certain SOAP API fields.
- Process all usage charges.
- If you have a Zuora for Salesforce integration, ensure that your Zuora for Salesforce packages are up-to-date.
Each of these steps is described in more detail below.
Ensure that your Zuora integration is using WSDL 69 or later
Zuora recommends that you ensure your integration is using WSDL 69 or later. Previous WSDL versions allowed you to pass dateTime values into certain date fields. WSDL 69 addresses this issue so that date fields behave correctly as date fields. As a result, any dateTime values passed into these date fields must be updated or they will be rejected.
See Date Field Changes in the SOAP API for a full list of fields that you need to check. See Zuora WSDL for information about downloading the latest WSDL version.
Ensure that you are not passing in time zone offsets to certain SOAP API fields
If you choose not to use WSDL 69 or later, Zuora recommends that you do not pass time zone offsets into the fields listed in Date Field Changes in the SOAP API. If you do pass a value with a time zone offset into one of these fields, the value is converted into Pacific Time (Zuora system time), regardless of your tenant time zone. This could cause the date to change, which might not be what you intended.
Example 1: Recommended - without a time zone offset:
If you pass the following value without a time zone offset into the ContractAcceptanceDate of a Subscription:
2016-01-01T05:00:00
The date remains unchanged:
2016-01-01T05:00:00-08:00
The subscription's contract acceptance date will be displayed as 2016-01-01 on the Zuora UI.
Example 2: Not recommended - with a time zone offset:
If you pass the following value with a time zone offset of +02:00 into the ContractAcceptanceDate of a Subscription:
2016-01-01T05:00:00+02:00
The value is converted to Pacific Time, which causes the date to change and might not be what you intended:
2015-12-31T19:00:00-08:00
The subscription's contract acceptance date will be displayed as 2015-12-31 on the Zuora UI.
Process existing usage charges
Zuora recommends that you perform a Bill Run to process all usage charges before changing your time zone.
After you change your time zone, the StartDateTime of any existing usage charges will be converted to your new time zone. However, these existing usage charges will still be processed by Bill Runs based on their original StartDateTime values from before you changed your time zone. For example, the following scenario could occur:
- You have an existing usage charge with a StartDateTime of
2015-06-30T23:00:00
. - You change your time zone to EST. The usage charge's StartDateTime value is correctly converted to EST:
2015-07-01T02:00:00-05:00
. - You perform a Bill Run for June. The usage charge is processed in the Bill Run for June, even though its StartDateTime value after changing your time zone is actually in July.
The behavior described above applies only to usage charges created before changing your time zone. Therefore, the easiest way to handle existing usage charges is simply to process them before changing your time zone. Any usage charges created after you change your time zone are processed in Bill Runs according to the StartTimeValue value based on your new time zone.
Ensure that Your Zuora for Salesforce packages are up-to-date
If you use Zuora CPQ, you must perform both of the following actions before changing your time zone:
- Upgrade your Zuora for Salesforce packages to the Q2 2015 release:
- Ensure your Zuora CPQ integration is using WSDL 69 or later.
What will happen after I change my time zone?
The following things will happen after you change the time zone.
Operations will be based on your new time zone
After you change your time zone, all UI and API operations will be based on the new time zone. For example, if you change your time zone to EST (Eastern Standard Time, GMT-05:00):
- Times on the Zuora UI will be converted to EST. A time previously displayed as 12:30 PST (Pacific Standard Time, GMT-08:00) will now be displayed as 15:30 EST. For example:
- A recurring Bill Run or Payment Run that was scheduled for 12:30 PST will continue to be executed at 12:30 PST, but the execution time displayed on the Zuora UI will be 15:30 EST.
- When you schedule a new recurring Bill Run or Payment Run, the time of day you select will be based on EST.
- DateTime values will be converted to EST. For example:
- Through the REST API: If a field returns a value of
2015-01-01T09:00:00
before you change your time zone, it will return2015-01-01T12:00:00
after you change your time zone. - Through the SOAP API: If a field returns a value of
2015-01-01T09:00:00-08:00
before you change your time zone, it will return2015-01-01T12:00:00-05:00
after you change your time zone.
- Through the REST API: If a field returns a value of
- Values passed into and returned from the SOAP API and REST API will be based on EST. For example, if you pass in 2016-01-01 as the contract effective date of a subscription, the subscription will become effective on 2016-01-01 at 00:00 EST.
Reports and Data Exports will be based on your new time zone
After you change your time zone, all reports and data exports will be based on the new time zone.
For example, if you change your time zone to EST, when you perform a data source export for all invoices created on 2015-01-01, the export will contain all invoices created on 2015-01-01 from 00:00 to 23:59 EST.
You should take the time shift into consideration when creating reports and data exports for dates close to the date that you changed your time zone. You can see when you changed your tenant time zone by navigating to Settings > Administration Settings > Manage Tenant Profile and looking under Change History.
The dates and times on the Z-Reporting > Reporting page UI will still be displayed in Pacific Time, even after you have changed to a new time zone. However, all reports generated through Reporting will be correctly based on your new time zone.
DateTime field behavior will change to reflect your new time zone
After you change your time zone, the behavior of dateTime fields in the SOAP API, Data Source Exports, and Export ZOQL will change to reflect your new time zone. See DateTime Field Behavior After Changing Your Time Zone for more information and example dateTime field values.