Time Zones
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. OR
Database sp057_regions
| 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 If 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 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 |