REST Objects Appointment Search

Defines as the inclusive date and time range between which appointments are required. (Note that start.time, and end.time does not represent the time band between which appointments should be returned every day within the range defined by start.date, and future. Date; that’s done using the band.start and band.end fields below.)If the date is omitted, ServiceOptimizer will use a default start date and time value of <now> plus the number of days specified in the Booking Lead Time for this JobType.If time is not supplied, it defaults to 0000 on the start date (above) but to <now> if the start date is <today>.

See above.

See above.  

The name of a time band that can be supplied to further filter out certain appointments and to modify the start and/or end times of the offers returned.

This is the name of the capacity category in which the the current job will belong to. If this parameter is not supplied then (in a system in which Capacity management is being used) the Capacity Category specified on the Job's Job Type is used.

Represents the days of the week for which appointments are required, starting on Monday. The character Y means that appointments whose arrival time (ETA) is on this day are required; any other character means they aren’t. YYYYYNN, for example, means that appointments are required for weekdays only. If a NULL string is supplied, the default value YYYYYNN is used.

When requesting appointments for long duration jobs, that are to be split across multiple shifts, the segments of the long job appointments will only occur on the requested day(s).

The amount of space occupied by equipment that will be removed from the operative’s vehicle as part of this job. SP_VEHICLE_CAPACITY_EXCEEDED (662) will be returned if no single vehicle within the FRU has a vehicle capacity large enough.

SS Field Mapping: deliverySize

unsigned integer

The time (in minutes) required to complete the job in addition to what is defined in ServiceOptimizer for the job's type. The maximum value that will be accepted for this field plus extraOverhead is specified by the SJEDMax database parameter. The maximum total duration for the job is specified by the SJTDMax database parameter.

SearchProcedure.JobDuration

The extra overhead time required to do this job in addition to the overhead time defined for the job's type. This is the extra time in minutes.

A list of additional skill (skillID),   needed in order to complete a given job in additions to those specified in ServiceOptimizer.  If an ExtraSkill is required, it should be set as the first and the ExtraSkillLevel should be different from that which is specified for the JobType. 

A total of 10 skill can be added, however only the first skillID listed can be assigned a SkillLevel. Additional skill are assumed to have no required SkillLevel.

Where this booking is based on offers from a previous call to OfferAppts, the values supplied in this field in this booking request must be the same as those supplied on the OfferAppts call.

The level of the extra skill required in the SkillID field, above. If the first of the SkillID specifies a skill which is already required by the JobType, then SkillLevel will replace the skill level required by the JobType for the first of the SkillID.

If a skill level is not required, the supplied value for this field should be 1

ExtraSkills.BrandCode

ExtraSkills.ProductCode

ExtraSkills.ServiceType

ExtraSkills.ProductCode

ExtraSkills.WarrantyType

See the Force Options section for the definitions of the permitted forceOptions listed below.

With the exception of IgnoreOverlap, forceOptions are not available for use in conjunction with long duration jobs that are to be split across multiple shifts; an attempt to set this will result in SP_FORCEOPTIONS_INVALID (150).

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).

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.

The sequence number of the first appointment of type numReqType required. For example, if 6 appointments are initially wanted, index is set to 1 and numReq to 6. If none of these appointments is acceptable, the next 6 available (of type numReqType) can be requested by setting index to 7 and leaving numReq at 6.

Note: This field has a maximum allowed value of 999.

Defined a preferred, mandatory or excluded operative for the job.

MulPrefServiceCenter[]

PrefServiceCenterID

The number of appointments required (of type numReqType, below). If not set, then a default is used (database parameter num_req_default).

This field has a maximum value of 99.

The total number of appointments returned may be fewer than the number defined by the numReq parameter, in the event that the requested number of appointments cannot be found.

However, the total number of appointments returned may also exceed the number defined by the numReq parameter, as appointments of different PromTypeIDs from those defined by the numReqType parameter may also be returned; however, the total number of appointments of the type requested will not exceed numReq.

SearchProcedure.NoAppt

The type of appointment (usually whole-day, half-day, or 2-hour) which numReq counts. If not set, then the type is inferred from bands in the specified promise set promSet (though if the promise set contains time bands of more than one type, SP_PROMSET_MULTIPLE_BAND_TYPES (645) is returned).

For long duration jobs, that are to be split across multiple shifts, only offers of this type are returned, even if the promSet also contains other types.

TBD - Determine if other OfferOptions listed within Scheduling documentation are valid.

See the Offer/Book Options section for the definitions of the permitted offerOptions listed below.

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

Note: When requesting appointments for long duration jobs, that are to be split across multiple shifts, overtime will only ever be used (when appropriate) for the final shift; overtime will not be used on any other shift.

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

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

When offerTextEmpID is also supplied, offers for different EmpIDs but that are otherwise identical may be returned.

If this option isn’t set, even though offerTextEmpID is supplied, offers that are for different EmpIDs 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.

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

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.

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.

Note: For Long jobs this parameter is not used and EmpId is always returned within the offer response.

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.

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.

The ID of the part.

The number of the parts ordered.

No

Optional field container object.

-

-

2

The name of the set of promise time bands to be used to translate available capacity into the returned offered appointments. If certain force options are to be used (see below) the promSet should contain only a single, all day, band.

SearchProcedure.ElementAttributes[].Name

Combined with the end parameter, defines an inclusive date and time range between which appointments are required.

Note that the start and end parameter's time values can not be used to define a time band between which appointments should be returned on every day within the range defined by the start and end parameter's date values; rather, the start and end parameters define only the start and end points of the range in which appointments are required.

To define a time band for each day in the range start to end range, use the band parameter.

In the event that an invalid inclusive date and time range between which appointments are required is specified, either SP_NO_TIME_AVAILABLE (8) or SP_END_NOT_GE_START_DATE (19) will be returned.

If the start date is not supplied, ServiceOptimizer will use a default start date and time value of <now> plus the number of days specified in the Booking Lead Time for the jobType.

Default Setting:  By default, the value will be should be formatted as though it's in UTC but since ServiceScheduling does not yet support UTC, the value actually represents customer local time.  Example: '2023-01-05T00:00:00.000Z'

SortBy (Rank - Servicer-Ranking, Date)

Specially defined extra time added to the normal amount for the job type. This time is specified in the DB.

The type of work to be performed.