Versions Compared

Version Old Version 44 New Version Current
Changes made by

Andrew Hill

Andrew Hill

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from space SCHUD and version 9.3
Panel

On This Page:

Table of Contents

Related Pages:

Panel

The sp:JobBookRequest API method can be used to book a job, without first obtaining an offered appointment.

Description

The sp:JobBookRequest API method creates a new job in ServiceOptimizer without having to go through the appointment offering process. It is normally used for business to business relationships where an exact appointment is not given to the customer; rather, an SLA or response time agreement is in place.

As with the Book Appointment SOAP API, this interface may be used to book long duration jobs (ones requiring more than one shift) with the system automatically choosing the best solution from the possible positions available.

Job Dates/Times

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

  • Contract Hours: This is the promised response window (ie ‘the engineer should respond within 48 hours of a call being raised’).
    • It is a pair of dates and times that represents the preferred time period when the job should be scheduled. This is equivalent to saying that the pair forms a soft constraint on when the job should be done, but it can be scheduled outside that period.
    • If a job is scheduled so that its ETA (ETF if it’s a call-to-fix job) is after its ContractLatest, it incurs an overdue cost proportional to the amount by which it’s late - but only during its service hours.
Service Hours: These are the hours of the day that the contract covers for entitlement (ie ‘the customer is entitled to 8 to 5 cover’).
  • As such they are the set of time periods during which a job’s overdue cost is applied, i.e. 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 each apply to a day of the week.
  • Each day of the week (DotW) has a StartTime and an EndTime defined. 
  • Where the EndTime is apparently before the StartTime, the EndTime is assumed to be on the next day. Therefore no service hours time period can be longer than 24 hours. There can be more than one service hours time period on each 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-gours cost is applied. The grace period does not vary by day of the week, and it must be supplied with a value between0 and 240.
  • There are two types of service hours patterns: 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). Each of these date ranges also acts as a hard constraint, i.e. the job should not be automatically scheduled outside them, and the overdue cost need only be applied during them.
  • 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.
    • Include Page_API servHoursPatts Definition_API servHoursPatts Definition
    • Access Hours: These are the hours where the customer site is physically open to undertake the work (ie. ‘nobody is in the building before 9am so it is not worth turning up 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). 
      • They act as a hard constraint, so a job’s ETA must be within its access hours (and so must its ETF if it’s a call-to-fix job).
      • 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:
        • 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.
        • as a set of open access hours overrides,
        • 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.
        • as being 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.
    Include Page_API accHoursPatts Definition_API accHoursPatts Definition
    Note

    A non-appointment job must have at least one access hours time period from one of the above mechanisms

    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 its access Hours:

  • The start time of the SSW is:
    • the later of the contract earliest time (if supplied) and {now}
    • and the end time is:
    the end of the day containing (the later of (contract latest time and {now}) + abs_sla_days_after)

    .

    Definition

    The definition of this API is:

    Include Page
    _API JobBookRequest Definition
    _API JobBookRequest Definition

    Return Structure

    The API returns a non-standard return structure.

    Include Page
    _API JobBookRequest Response
    _API JobBookRequest Response

    Return Codes

    In addition to the Standard Return Codes, the possible Return Codes from this API are:

    Include Page
    _API JobBookRequest Return Codes
    _API JobBookRequest Return Codes