On This Page:

Related Pages:

Contract and Service Hours

The dates and times that define valid periods in which a job may be booked fall into three categories, which usually are related to the contract that is in place with the customer.

Contract Hours

Contract Hours represent a promised response window - for example, ‘an engineer should respond within 48 hours of a call being raised’.
- Contract Hours are a pair of dates and times that represent the time period when the job should be scheduled.
- If a job is scheduled so that its ETA (ETF if it’s a call-to-fix job) is after ContractLatest, it incurs an overdue cost proportional to the amount by which it’s late - but only during its service hours.

Service Hours

Service Hours represent the hours of the day that a customer contract covers for entitlement - for example, ‘the customer is entitled to 8 am to 5 pm cover’.
- As such, Service Hours are the set of time periods during which a job’s overdue cost is applied. That is, the overdue cost is proportional to the amount of time during its Service Hours that a job’s ETA (or its ETF if it’s a call-to-fix job) exceeds its ContractLatest time.
- A Service Hours pattern is a repeating sequence of Service Hours time periods that apply to a given day of the week.
- Each day of the week (DotW) has a StartTime and an EndTime.
- Where the EndTime is before the StartTime, then then EndTime is assumed to be on the next day.
- A Service Hours time period can not be longer than 24 hours.
- There can be more than one Service Hours time period per day.
- The time not within the Service Hours defines a set of time periods during which a job’s out-of-Service-Hours cost is applied.
- There can be a ‘grace period’ (in minutes) after the end of each Service Hours time period before the out-of-Service-Hours cost is applied. The grace period does not vary by day of the week, and it must be supplied with a value between 0 and 240.
- There are two types of Service Hours pattern: named (pre-defined) patterns and unnamed patterns:
  - Named Service Hours patterns are pre-defined in ServiceOptimizer so that a job can be booked with just the name of that Service Hours pattern supplied as a parameter.
  - Instead of having a pre-defined Service Hours pattern, a job can be booked with its own (unnamed) Service Hours pattern, i.e. one that is not pre-defined in ServiceOptimizer but is supplied with the job when it is booked.
    - For this, a pattern of DayAndTimePeriods must be supplied for each day of the week that the Service Hours should apply.
- Each job can have only one Service Hours pattern (pre-defined or unnamed), but it can optionally be assigned over one or more date ranges (SP_DateRange, below).
- Jobs booked with no Service Hours pattern (i.e. both ServHoursPatts and ServHoursPreDefPatts in the JobBookRequest structure supplied in a call to the sp:JobBookRequest API method are NULL) will use a default Service Hours pattern called fru_default_shp defined in the database.
- When a job is booked, it is possible to specify closed dates (ClosedDates in the JobBookRequest structure) during which the Service Hours won’t be applied, i.e. the job does not become any more overdue during these dates. ClosedDates is defined as a set of DateRanges.

Click here to expand...

Web Service				Type	Description	Req?	Val?
`<servHoursPatts>`					A repeating sequence of Service Hours time periods that each apply to a day of the week. `ServHoursPatts` can not be supplied as well as `ServHoursPreDefPatts`.	N
	`<servHoursPatt>`
		`<dateRange>`			The date ranges can be ‘open-ended’ in the sense that either the `StartDate` or the `EndDate` (or both) may be missing, in which case the Service Hours pattern is assumed to continue ‘forever’ in the corresponding direction.
			`<start>?</start>`	`spDate`		N
			`<end>?</end>`	`spDate`		N
		`</dateRange>`
		`<dayAndTimes>`			The actual Service Hours (`DayAndTimePeriod` and `GracePeriod`) for each must be the same, though the `DateRanges` can be different. Each day of the week (`DotW`) has a `StartTime` and an `EndTime` is a set of Service Hours patterns supplied just for this job.	Y
			`<day>?</day>`	`DayOfTheWeek`		Y
			`<start>?</start>`	`Time`		N
			`<end>?</end>`	`Time`		N
		`</dayAndTimes>`
		`<gracePeriod>?</gracePeriod>`				Y
	`</servHoursPatt>`
`</servHoursPatts>`

Access Hours

Access Hours represent the hours where the customer site is physically open to undertake the work - for example, ‘nobody is in the building before 9 am so possible to do the job before then because the engineer will not be able to gain access to do the job’.
- Access Hours are an optional set of time periods during which a job can be started (for example when the customer premises are open).
- There are no pre-defined Access Hours patterns, so each job’s Access Hours may only be supplied when it is booked.
- There are several ways in which Access Hours can be specified for a job, all of which, except for the first and fourth options below, can apply at the same time:
  1. As a weekly repeating open Access Hours pattern over one or more date ranges. An Access Hours pattern is a repeating set of Access Hours time periods that each apply to a day of the week. The actual Access Hours (DayAndTimePeriodSeq) must be the same in each SP_AccHoursPatt, though the DateRanges can be different.
  2. As a set of open Access Hours overrides.
  3. As a set of closed Access Hours overrides that are time periods during which the job must not be started (or finished for a ETF job). Closed Access Hours overrides can only be added to existing Access Hours; there is no replace option. Closed Access Hours overrides are also converted into open overrides before being stored and subsequently never appear as closed overrides.
  4. As the same as the Service Hours (see ServAsAccHours). If the Service Hours are to also act as Access Hours the Access Hours end after the end of the grace period, if there is one, and it is an error to also supply an Access Hours pattern, though Access Hours overrides are allowed.

Click here to expand...

Web Service					Type	Description	Req?	Val?
	`<accHoursPatts>`					A set of Access Hours patterns for the job. The actual Access Hours for each pattern must be the same, though the `DateRange` can be different.	N
		`<accHoursPatt>`					Y
			`<dateRange>`			The date ranges can be ‘open-ended’ in the sense that either the `Start` or the `End` (or both) may be missing, in which case the Access Hours pattern is assumed to continue ‘forever’ in the corresponding direction.
				`<start>?</start>`	`spDate`		N
				`<end>?</end>`	`spDate`		N
			`</dateRange>`
			`<daysAndTimes>`				Y
				`<day>?</day>`	`DayOfTheWeek`		N
				`<start>?</start>`	`Time`		N
				`<end>?</end>`	`Time`		N
			`</daysAndTimes>`
		`</accHoursPatt>`
	`</accHoursPatts>`

Any non-appointment Job must have either:

A set of Access Hours specified by one of the above mechanisms
OR
Must have at least one open Access Hours override.

If it has an open Access Hours override then it does not have to have Access Hours at all.

Allocation Mechanism

The search for available capacity will be limited to the SLA Search Window (SSW) which is based on a combination of the job’s Contract Hours and Access Hours:

The start time of the SSW is either:
- If "contract earliest" is being treated as a soft constraint:
  - {now}
- If "contract earliest" is being treated as a hard constraint:
  - The later of the contract earliest time (if supplied) and {now}
The end time of the SSW is:
- The end of the day containing:
  - The later of (contract latest time and {now}) + abs_sla_days_after

Browser not supported