Name

string

SS:JobTypeID (string)

SS: 30

Must be one of the job types (aka task codes) set up in ServiceOptimizer

SS Field: jobType

Address

This represents the customer's address associated with the job.

Yes

LocationNum

string

SS: 20

An identifier for the customer for whom this job is booked.

SS Field: customer.custID

Name

string

SS: CustName (string)

SS: 50

The name of the customer.

SS Field: customer.custName

SiteId

string

SS: SiteID

SS: 20

Each job can optionally have a Site Identifier.  ServiceOptimizer will attempt to schedule jobs with the same SiteIDs: (a) consecutively, so that there’s zero travel time between them, and (b) with the overhead time (from the Job Type and the supplied ExtraOverhead) removed from all but the first of them.  ServiceOptimizer treats the SiteID as an opaque value that it uses only to group jobs together.

SS Field: siteID

Contacts

Jobs of long duration cannot be rebooked – if this field is true, and the JobID already exists and is a long job, then SP_MULTIJOBID_ALREADY_EXISTS (539) will be returned

For all other jobs, if this field has the value SP_True, the call to JobBookRequest will not fail if the JobID already exists in the ServiceOptimizer database. Instead, the existing job is deleted and replaced by this one. If AllowRebook is set and the job doesn’t already exist, the JobBookRequest call continues anyway.

SS Field: allowRebook

string

SS: EmpID

Names preferred, mandatory or excluded operatives for this job.

SS Field: ListReqEmps.empID

Yes

• Must do the job (i.e. Mandatory, or M);
• Are Preferred (or P) to do the job; or
• Must not do the job (i.e. Excluded, or X).

Accordingly, the Mandatory, Preferred and Excluded options are referred to simply as MPX.

SS Field: ListReqEmps.MPX

SS Valid Values: "None", "Preferred", "Mandatory","PreferredOrdered", "MandatoryOrdered", "MandatoryNot","MAX"

Yes

string

SS: UnitType

SS: See Valid Values

If Mandatory, specifies that the job must only be assigned to an employee in the FRU or DRU supplied in the supplied Unit field (below), i.e. the supplied FRU or DRU is mandatory. Values other than Mandatory are not implemented and will cause SP_REQTYPE_INVALID (74) to be returned. The only supported combinations of this and the next two fields are: (1) Mandatory, Final and an FRU ID, or (2) Mandatory, SPUT_D and an DRU ID.

SS Field: reqUnit.unitType

SS Valid Values: "FRU", "DRU"

Yes

string

SS: RUID (string)

SS: 8

SS Field: reqUnit/RUID

Yes

BookLocID

string

SS: BookLocID (string)

SS: 4

Unique identifier of the location (or service) from which the job is booked. If at a later time, for example when a job becomes earmarked, ServiceOptimizer needs to send out a message, this location is used to look up (in the ServiceOptimizer database) the address of the service it is sent to.

SS Field: bookLoc

No

ContractEarliest

string

SS: spDateTime (string) 

SS: 16

The earliest time that the job should be started (ETA). If  ContractEarliest is not supplied, then ContractEarliest will be defaulted to <now>.

Example: "2023-03-30T14:15"

SS Field: contractEarliest

ContractLatest

string

SS: spDateTime (string) 

SS: 16

The time by which the job should either be started (ETA) or completed, depending on the value of callToFix.

Example: "2023-03-30T14:15"

SS Field: contractLatest

Offer

OpenAccHoursOvrs

A set of open Access Hours overrides for this job. 

If overlapping open Access Hours override periods are supplied, the overlaps are silently removed – two overlapping open Access Hours overrides will be merged into one, for example.  Similarly, overlapping closed Access Hours overrides periods are also merged.

No

ClosedAccHoursOvrs

A set of closed Access Hours overrides for this job.  Closed overrides are converted into open overrides before being stored.

No

ClosedPubHols

No

ClosedDates

A set of closed dates (i.e. closed whole days) for this job. ClosedDates applies only to Service Hours, not to Access Hours.

No

ServHoursPreDef

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.

Yes

string

SS: integer

SS Field: servHoursPatts.servHoursPatt[].gracePeriod

Yes

Yes

AllowEmpOT

The employees’ maximum allowed overtime should be included when making appointment offers.

SS Field: AllowEmpOT

No

SpareIgnVanStock

The spareIgnVanStock option indicates to ServiceOptimizer that vehicle stock should be ignored when generating appointments. Any ReqSpares data supplied as part of the offer request will still be read in by ServiceOptimizer, but SP_SPAREID_INVALID (111) will not be returned if any of the supplied ReqSpares is not in the ServiceOptimizer database.

If spareIgnVanStock is set then the SpareForceGo (see ForceOptions) flag will be ignored.

SS Field: SpareIgnVanStock

No

FixToEmp

This option will cause the chosen operative to effectively become mandatory.

SS Field: FixToEmp

No

ServAsAccHours

This option makes the job’s access hours pattern the same as its service hours pattern. (If an access hours pattern is also supplied in an AccHoursPatts structure, SP_ACCHOURS_DUPLICATED (390) will be returned.)

SS Field: ServAsAccHours

No

CallToFix

This option specifies that the job’s ETF will be used instead of its ETA to calculate its lateness (using its Service Hours), and will be used as well as its ETA to determine if it’s outside its access hours.

SS Field: CallToFix

No

ReqConfirm

This option will indicate on the Gantt that this job should be confirmed.

SS Field: ReqConfirm

No

NonConsecShift

Allows the use of non-consecutive shifts (as well as allowing contiguous and consecutive shifts) for splitting long duration jobs

SS Field: NonConsecShift

No

ConsecShift

This option requests the use of consecutive shifts (as well as allowing contiguous shifts) for splitting long duration jobs.

SS Field: ConsecShift

No

ContigShift

This option requests the use of only contiguous shift time splits for long duration jobs.

SS Field: ContigShift

No

InTray

A ‘catch all’ option to by-pass all constraint checking. The job is not even provisionally allocated to an operative, but remains in an in-tray until it is either manually allocated or another attempt is made to allocate it through the ABS. Both of these operations are done from the Gantt. The job will only be put into the in-tray of one of the FRUs that is mapped to the job’s location (region). Exactly which FRU is undefined, but it won’t be put into an FRU with no posted operatives.

If a mandatory FRU is supplied, the job will be booked into that FRU. If a mandatory DRU is supplied, the job will be booked into an FRU in that DRU.

If one or more mandatory Employees are supplied, but no mandatory FRU or DRU, the job will be booked into an FRU where one of those Employees has a posting (during the memory horizon) to one of the FRUs mapped to the job’s location.

If one or more mandatory Employees are supplied as well as a mandatory FRU, the job will be booked into that FRU as long as at least one of those Employees has a posting to that FRU at some time during the memory horizon.

If one or more mandatory Employees are supplied as well as a mandatory DRU, the job will be booked into an FRU in that DRU as long as at least one of those Employees has a posting to that FRU at some time during the memory horizon.

SS Field: InTray

No

InTrayWithSkill

Is another option to by-pass constraint checking, though the job will still only be put into the in-tray of one of the FRUs that is mapped to the job’s location (region). However, a skills check is done when placing the job: If there is one FRU containing an employee with the skills to do the job at some time during the SLA Search Window (see 6.6), even if that employee is not available, then the job will be put into that FRU’s in-tray. If there is more than one FRU, the one with the (numerically) lowest preference factor will be chosen. If there is more than one FRU with the same preference factor, one of them will be chosen, but which one chosen is undefined. If one or more mandatory employees are supplied, they will be stored but otherwise ignored. If a mandatory FRU is supplied it will be ignored (and not stored). If a mandatory DRU is supplied, it will be ignored.

SS Field: InTrayWithSkill

No

InTrayAfterAll

First attempts to allocate the job in the normal way. If this isn’t possible, and neither a mandatory DRU nor a mandatory FRU nor mandatory employees are supplied, the job is booked into an FRU where, during the SLA Search Window, there is at least one employee with the skills to do the job (similar to InTrayWithSkills). The Gantt can then be used to try to allocate it, either manually or through the ABS again.

If a mandatory FRU is supplied in ReqUnitType, UnitType and Unit, then the job will be put into that FRU’s in-tray as long as there is an employee in that FRU with the required skills during the SLA Search Window (though he may not be available). If this is not the case, SP_UNIT_INVALID (28) is returned.

If a mandatory DRU is supplied, the job will be put into the in-tray of one of the FRUs in that DRU as long as there is an employee in that FRU with the required skills during the SLA Search Window (though he may not be available). If this is not the case, SP_UNIT_INVALID (28) is returned.

If one or more mandatory employees are supplied in ReqEmpType and EmpID, a check will be made that one of them has the skills to do the job (at some time during the SLA Search Window), and the job will be put into the in-tray of the FRU where one of those employees is working. If none of them have the skills, SP_EMP_NOT_SKILLED (75) will be returned. If the employee is working in more than one FRU, the job will be put into the in-tray of the FRU with the (numerically) lowest preference factor. If there is more than one FRU with the same preference factor, then which of those is chosen is undefined.

If both a mandatory FRU and one or more mandatory employees are supplied, and the employees aren’t posted to the FRU at any time, the job will be put into the in-tray for the mandatory FRU as long as, during the memory horizon, there is at least one employee with the skills.

If both a mandatory DRU and one or more mandatory employees are supplied, and the employees aren’t posted to any of the FRUs in that DRU at any time, the job will be put into the in-tray of one of the FRUs in that DRU as long as, during the memory horizon, there is at least one employee with the skills.

In all cases, the job will only ever be booked into an FRU that its location (region) is mapped to.

Note: The 3 In-Tray ForceOptions (above) are mutually exclusive. SP_OPTION_COMBINATION_INVALID (159) will be returned if more than 1 of them is set.

SS Field: InTrayAfterAll

No

SpareForceGo

Indicates that a job that requires spares should still be allocated even if all of the required spares are not available. This means that if all the spares are available from vehicle stock they may be used, otherwise they need to be sourced externally.

SS Field: SpareForceGo

No

Reassign

Allows existing jobs to be re-assigned among operatives in an attempt to fit this new job into the schedule. Use of this option will increase response times; this may be controlled by means of the database parameters ABS_reassign_jobs_max, ABS_reassign_options_max, and ABS_reassign_timeout.

SS Field: Reassign

No

IgnoreCapacity

When set to true, the capacity for every day should be treated as though it was 100%, i.e. the capacity check values set for each day should be ignored.

SS Field: IgnoreCapacity

No

NoTravel

Sets the travel time (travel-to) to zero. i.e. Jobs with “NoTravel” are skipped in travel calculations. Travel time to next location will be based on previous location.

SS Field: NoTravel

No

NoLocalKnowledge

Ignores local knowledge checks in candidate searches.

SS Field: NoLocalKnowledge

No

IgnoreAvailable

When set to true, jobs can be offered/booked onto operatives who are not available. Jobs booked with ignoreAvailable  are not moved by the optimizer until the operative becomes available.

SS Field: IgnoreAvailable

No

IgnoreSkills

When set to true, jobs can be offered/booked onto operatives who lack the required skills for the job.

SS Field: IgnoreSkills

No

spare

string

SS: SpareID (string)

SS: 30

SS Field: reqSpares.reqSpare[].spare

Yes

string

SS: integer

SS Field: reqSpares.reqSpare[].quantity

Yes