14.1 Time Zones

On This Page:

Times in the Database
To run in a single Time Zone
Setting up for multiple Time Zones
Local Time Type
Time Zone Parameters

Time Zones play an important part in the ServiceOptimizer system. This section covers how they are set up and used.

Times in the Database

In the database there is no time zone specified for most date/time columns. It is the user of that information who has to decide which time zone is needed. Times are held in the time zone of the object (FRU, operative or region) which owns them.

Owner TZ Description/rules

shifts and shift overrides

are in operative local time Database sp210_employees.tz_no and tz_type

OR

Database sp057_regions tz_no

(if sp210_employees tz_type = 1)

An employee may, through a working day, move between different time zones. The employee’s schedule for the day could be represented in terms of the time zone of the location in which s/he is in at any given time, but it is more sensible to assume that the employee has a watch and is working to his/her own local time zone.

If the tz_type field is set to 0, the tz_no field is used, and if is NULL, the system parameter tz_Default is used.

If tz_type is 1, then the time zone of the employee’s home region is used.

A level 3 region can have an associated time zone. A level 1 region will hold the default for its owned level 2 regions. A level 2 region will hold the default for its owned level 3 regions. If this field is NULL, the time zone applied is found by recursively looking at the time zone of the owning region (up to level 1 region). Otherwise if no owning region has a time zone, the system parameter tz_Default is used.

job times are in the local time of the FRU they are assigned to Database sp058_responsibility_units tz_no The time zone associated with a responsibility unit does not confine it to including only regions within a single time zone. If this field is NULL and resp_unit_type is 1 (final) then the system parameter tz_Default is used. If this field is NULL and resp_unit_type is 0 (interim) then the time zone of the owning final RU is used, or the system parameter tz_Default is used if the owning final RU has no time zone specified. Note that setting this field for resp_unit_type 0 (interim) is only effective for Dispatch.

travel profile times are in the local time of their region

The time zone definitions for all time zones covered by the ServiceScheduling instance are held in table Database sp056_time_zones, with a default value held in the parameters table Database sp083_system_parameters. ServicePower have preloaded sp056_time_zones with standard POSIX values. The user can load other values into sp056_time_zones provided they are compatible with the platform definitions. The values required for referencing from other tables is the tz_no, however a description of the time zone for any row of this table can be found in the field tz_long_name.

UNIX Only

See the ‘man date’ pages for an explanation of the formatting used in variables beginning ‘tz_fn…’

You must not change the pre-defined values in sp056_time_zones.

The default in tz defined in sp083_system_parameters is GMT, that is tz_no = 1.

To run in a single Time Zone

The few lines below are all that are required to cause all operatives, regions and RUs to use the default time zone.

update sp210_employees set tz_type=null, tz_no=null;
update sp057_regions set tz_no=null;
update sp058_responsibility_units set tz_no=null;
 
update sp083_system_parameters set value='<tz_no>' where name='tz_Default';

Setting up for multiple Time Zones

If there is a requirement to run across more than one time zone, each Responsibility Unit must be assigned to a time zone. Having assigned RU’s to time zones the next step is to do the same for Operatives and Regions. These may have different time zones from their owning RU.

Table sp083_system_parameters holds a number of default time zones types for each of the entity types where time zone is relevant and it is essential, therefore, that time zones are not defaulted without consideration of the settings in sp083_system_parameters. The default values in the table should be reviewed at installation time. The parameters are described below

As mentioned previously, there is an overall default time zone, tz_Default, which has been set to ‘1’ i.e. the time zone ‘GMT’. If an entity has not been assigned a time zone then the default for that entity type in sp083_system_parameters will be used. If that default has not been set then the overall default tz_Default will be used. The setting of tz_Default should be reviewed at installation time and altered if necessary to a more appropriate value.

Local Time Type

Local Time Type values are used so that the time zone of API inputs and outputs may be customised. The value specifies which mapping to use as follows:

Value	tz to be used
0	Customer local time, i.e. the D&Ts are local to the TZ of the region where the job is located. This is also the value assumed if it is present but has no value, or is not present at all.
a tz_ref	which is in sp056_time_zones, e.g. “Eastern”
2	RU local time
3	Employee local time
4	Reserved
5	Reserved
6	GMT0 (i.e. time_t expressed as a character string)
7	GMT0BST (i.e. GMT with daylight saving)

Important Notes

Use of value 4 results in the default time zone being used.
Use of value 5 results in the default time zone being used.
For tz_BJAPIIn only value 0 (customer local time) is supported.
For tz_GJAPI, tz_GJAPIUnres and tz_GAAPI values 4, 5 or any invalid tz_ref will halt the start up of the system.

Time Zone Parameters

There are a number of parameters associated with Time Zones for many ServiceOptimizer processes, entities and APIs (see 14.1 New Instance Set Up and Integration Guide), taking values from Local Time Type. The most important sp083_system_parameters and their meanings are described below.

Parameter	Description/Purpose
tz_BJAPIIn	Used to specify which time zone should be assumed when using the BookJob API.
tz_CJS	Change Job Status local time type. Also used for ChangeWorkItemStatus, and ChangeJobDateTime APIs
tz_Default	Time zone identifier for the default time zone. Used when either a database object has no specified time zone or a standard time zone is required, e.g. for logging. Must be a valid sp056_time_zones.tz_no
tz_disp_api	Dispatch API local time type. Used to specify which time zone should be assumed for all outgoing job information. This is not necessarily so relevant now as the APIs allow the request for dates and times to be given in UTC with an offset for the TZ in question, so the calling system does not need to know in advance which TZ it is going to receive.
tz_GAAPI	Get Activity API local time type
tz_GJAPI	Get Job (resourced) API local time type
tz_jeop_api	Local time type for Jeopardy API time zone view
tz_opts	Timezone for GPS API timestamp