On This Page:

Offer/Book Options
Force Options
Standard Activity Options

Related Pages:

Most of the SOAP APIs contain ‘options’ fields, which allow particular options specific to that interface to be passed to ServiceOptimizer. If a particular option is required it should be supplied, with a boolean value of true. If the option is not required it should be omitted from the call.

Offer/Book Options

These options are used for the Request Appointments SOAP API, Request Multi-Job Appointments SOAP API, Book Appointment SOAP API, Book Non-Appointment Job SOAP API and the Update Non-Appointment Job SOAP API.

Not all options are available for all interfaces and the relevant sections should be referred to for the valid listing.

Option Name	Type	Definition
`AllowEmpOT`	`boolean`	The employees’ maximum allowed overtime should be included when making appointment offers.
`CalltoFix`	`boolean`	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.
`ConsecShift`	`boolean`	This option requests the use of consecutive shifts (as well as allowing contiguous shifts) for splitting long duration jobs.
`ContigShift`	`boolean`	This option requests the use of only contiguous shift time splits for long duration jobs.
`DupUseEmpID`	`boolean`	When `offerTextEmpID` is also supplied, offers for different `EmpID`s but that are otherwise identical may be returned. If this option isn’t set, even though `offerTextEmpID` is supplied, offers that are for different `EmpID`s but are otherwise identical are considered to be duplicates and only the lowest cost one may be returned. If `dupUseEmpID` is set but `offerTextEmpID` isn’t, then `dupUseEmpID` is ignored.
`FixtoEmp`	`boolean`	This option will cause the chosen operative to effectively become mandatory.
`NonConsecShift`	`boolean`	Allows the use of non-consecutive shifts (as well as allowing contiguous and consecutive shifts) for splitting long duration jobs
`OfferBestOnlyPerEmp`	`boolean`	If supplied, then only the *best* set of offers for each available employee will be returned. The best offer is the earliest one whose `PromType` matches the supplied `NumReqType`. If not set, more than one set of offers for each employee can be returned.
`OfferTextCost`	`boolean`	Requests that the cost of the offer be returned as part of the `OfferText`. The cost returned will be the difference in travel cost between the job being in the position of the offer as opposed to it not being there.
`OfferTextEmpID`	`boolean`	The `ID` of the operative notionally given the job will be returned in the offer. However it should be remember if using this that ServiceOptimizer may optimize it to another operative at any time.
`RemoveMandatory`	`boolean`	This option will cause any previously specified mandatory operatives (1 or 2, ordered or not) to be removed from the job. An error won’t be returned if the job has no mandatory operatives. This option has no effect on preferred or excluded operatives.
`RestrictSearch`	`boolean`	The search for sets of offers biased towards those employees for whom the greater numbers of possible offers were found for the first jobs in the request.
`ReqConfirm`	`boolean`	This option will indicate on the Gantt that this job should be confirmed.
`ServAsAccHours`	`boolean`	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.)
`SetConfirmed`	`boolean`	This option sets the `ConfirmedState` of the job to `Confirmed`.
`SetDispStatusBack`	`boolean`	This option will cause the job’s dispatch status to be set to `Tentative`.
`SetNotFixed`	`boolean`	This option will remove the fixed flag from the job (if it were previously fixed).
`SpareIgnVanStock`	`boolean`	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.
`SetUnEarmark`	`boolean`	This option will cause an unearmark to be generated (should one be required).
`UseAccessHours`	`boolean`	This option's effect is to cause access hour overrides to be generated from the job’s existing access hours (which may be from an access hours pattern) that overlap the same operative day on which the job’s ETA is current scheduled. If the job has no access hours on that operative day, a single access hours override from the start of the operative day to the end will be set.
`useExtraDuration`	`boolean`	This option's effect is to, for jobs with a `JobType` that allows the job to be split, only use the supplied `extraDuration` field when calculating the total duration of the job parts - the duration from the `JobType` is ignored. However, for jobs with a `JobType` that does not allow the job to be split, the `useExtraDuration` option will be ignored. When the `useExtraDuration` option is used: There is no minimum value for `extraDuration,` although it must be > 0. The parameters `SJEDMax` and `SJTDMax` will not be applied, however, there will be a maximum allowed: `extraDuration` < `JobType` duration. All other aspects of total duration of the job parts are unaffected; specifically, the extraOverhead and stdExtraDuration are added in the same way as normal.
UseFRUFilter	boolean	This is a RESERVED option for internal use only. It allows the Rebook function in Gantt to prevent offers being filtered out by the API Agent when determining a list of FRU's that can accept the job. It will ensure that the FRU string is used to ignore all other fields in the filter detecting uniqueness. Thus only one offer from each responding FRUs should be returned. If used then the action of the following options will be ignored in the Apaigent but not in the FRU: OfferTextEmpID DupUseEmpID InTray

Force Options

These options are used for the Request Appointments SOAP API, Book Non-Appointment Job SOAP API and the Book Dependency Group Jobs SOAP API.

Not all options are available for all interfaces and the relevant sections should be referred to for the valid listing.

Option Name	Type	Definition
`ignoreAvailable`	`boolean`	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.
`IgnoreCapacity`	`boolean`	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.
`IgnoreOverlap`	`boolean`	For use in calls to the Request Appointments SOAP API under circumstances where a follow on set of part jobs is to be booked via the Book Split Dependency Group Jobs SOAP API. When set to true, if it is impossible to find spaces for all required job parts, then the offers returned are able to include places where other work items would be overlapped. A mandatory employee must be supplied, if not, then setting `IgnoreOverlap`, will return `SP_OPTIONS_INVALID (80)`.
`ignoreSkills`	`boolean`	When set to true, jobs can be offered/booked onto operatives who lack the required skills for the job.
`Intray`	`boolean`	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.
`IntrayAfterAll`	`boolean`	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.
`IntrayWithSkill`	`boolean`	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.
`NoLocalKnowledge`	`boolean`	Ignores local knowledge checks in candidate searches.
`NoTravel`	`boolean`	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.
`Reassign`	`boolean`	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`.
`SpareForceGo`	`boolean`	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.

Standard Activity Options

Option Name	Type	Definition
`CheckFrozen`	`boolean`	`SP_FROZEN_DAY (585)` is returned if the new activity would be on a date where the engineer’s schedule is frozen.
`CheckJobDealloc`	`boolean`	If the new standard activity would overlap existing jobs, those jobs are de-allocated (to the in-tray), unless their status is `SPDS_LoggedOff` or `SPDS_Cleared`, in which case they will be left overlapping. The new activity is created. If none of these options is set the new activity is created anyway and any consequent overlaps are left as they are.
`CheckJobs`	`boolean`	`SP_OVERLAPPED_JOBS (132)` will be returned if the new activity would overlap existing jobs. The new activity is not created.
`CheckJobsAllowBreakAH`	`boolean`	If this is also set with the above option, the shuffled jobs’ access hours can be broken to remove overlaps.
`CheckJobsShuffle`	`boolean`	Existing Tentative, Earmarked and Contacted jobs will be shuffled to try to remove overlaps. If removing the overlaps would mean the jobs’ access hours would be broken, then the call is aborted and `SP_WOULD_BREAK_ACCESS_HOURS` (371) is returned.
`CheckStdActs`	`boolean`	`SP_OVERLAPPED_STDACTS (160)` will be returned if the new activity would overlap existing standard activities. The new activity is not created.
`OverlapBreaks`	`boolean`	Currently not used. This option has been added for future use in determining the behaviour when breaks are overlapped by standard activities.

Browser not supported