Appointment Search Object: ServiceScheduling

5.0.0

The Appointment Search Object provides the appointment search properties used to define a appointment search request. Once the search parameters have been defined, the local CRM platform can use it to locate available appointments that match the search request.

When a Appointment Search REST API call results in an appointment search request being directed to ServiceScheduling, the fields that are present in the Appointment Search Request Object (below) will be passed to ServiceScheduling and provide ServiceScheduling with instructions on how to handle (and respond to) the request.

Please see the appropriate version of the ServiceScheduling sp:ApptOfferRequest API for the field definitions.

On this page:

Related pages:

Appointment Search Object Format

Json Format

{
    "Band": {
        "Start": "",
        "End": "",
        "TimeBandID": ""
    },
    "CapacityCategory": "",
    "Days": "",
    "DeliverySize": 0,
    "EndDate": "",
    "ExtraDuration": 0,
    "ExtraOverhead": 0,
    "ExtraSkills": [
        {
            "SkillID": "",
            "SkillLevel": "",
            "Mfg": "",
            "ProdLine": "",
            "ServiceType": "",
            "WarrantyType": ""
        },
        ...
    ],
    "ForceOptions": {
        "IgnoreCapacity": true,
        "IgnoreOverlap": true,
        "InTray": true,
        "InTrayWithSkill": true,
        "NoLocalKnowledge": true,
        "NoTravel": true,
        "Reassign": true,
        "SpareForceGo": true
    },
    "GroupID": "",
    "Importance": "",
    "Index": 0,
    "ReqProvider": [
        {
            "Id": "",
            "MPX": ""
        },
        ...
    ],
    "Location": {
        "Latitude": "",
        "Longitude": "",
        "Postcode": "",
        "Country": "",
        "SiteID": ""
    },
    "MaxOffers": 0,
    "NumReqType": 0,
    "OfferOptions": {
        "AllowEmpOT": true,
        "ConsecShift": true,
        "ContigShift": true,
        "DupUseEmpID": true,
        "NonConsecShift": true,
        "OfferTextCost": false,
        "OfferTextEmpID": false,
        "SpareIgnVanStock": false,
        "UseExtraDuration": false
    },
    "PickupSize": 0,
    "PreferredDate": "",
    "Part": [
        {
            "VendorId": "",
            "VendorName": "",
            "Id": "",
            "Type": "",
            "Qty": 0
        },
        ...
    ],
    "Product": {
        "Mfg": "",
        "ProdLine": ""
    },
    "PromSet": "",
    "RankingCutoff": "",
    "ReqUnit": {
        "RUID": "",
        "UnitType": ""
    },
    "SearchProcedure": {
        "ProcedureCode": "",
        "ElementAttributes": [
            {
                "Name": "",
                "Value": ""
            },
            ...
        ]
    },
    "StartDate": "",
    "SortBy": "",
    "StdExtraDuration": "",
    "WarrantyType": "",
    "WorkType": {
        "Name": ""
    }  
}

Appointment Search Object Properties

Property Type Length Description

Band

object

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

Property

Type

Length

Description

Start

string

4

See above.

SS Field Mapping: band.start

End

string

4

See above.

SS Field Mapping: band.end

TimeBandID

string

4

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.

SS Field Mapping: band.timeBandID

CapacityCategory

string

20

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.

SS Field Mapping: capacityCategory

Days

string

7

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

SS Field Mapping: days

DeliverySize

integer

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

EndDate

DateTime

Combined with the StartDate parameter, defines an inclusive date and time range between which appointments are required. See the description of the StartDate parameter for details.

SS Field Mapping: end.date + end.time

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'

ExtraDuration

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.

SS Field Mapping: extraDuration

ExtraOverhead

integer

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.

SS Field Mapping: extraOverhead

ExtraSkills

array

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.

Property	Type	Length	Description
SkillID	string	30	SS Field Mapping: extraSkills.reqSkills[].skillID
SkillLevel	unsigned int		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` SS Field Mapping: extraSkills.reqSkills[].skillLevel
Mfg
ProdLine
ServiceType
WarrantyType

ForceOptions

object

TBD - Determine if other options currently available in ServiceScheduling are available within Broker.

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

Property	Type	Description
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. SS Field Mapping: forceOptions.IgnoreCapacity
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)`. SS Field Mapping: forceOptions.IgnoreOverlap
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. SS Field Mapping: forceOptions.InTray
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. SS Field Mapping: forceOptions.InTrayWithSkill
NoLocalKnowledge	boolean	Ignores local knowledge checks in candidate searches. SS Field Mapping: forceOptions.NoLocalKnowledge
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. SS Field Mapping: forceOptions.NoTravel
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`. SS Field Mapping: forceOptions.Reassign
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. SS Field Mapping: forceOptions.SpareForceGo

SS Mapping: forceOptions

GroupID

string

30

Jobs with the same groupID should be allocated in the minimum number of contiguous groups that are needed to meet their Access Hours constraints. Like a siteID, a groupID is treated as an opaque value by ServiceOptimizer.

SS Field Mapping: groupID

Importance

integer

When set, will generate offers for a more important job by assuming that less important jobs can be de-allocated when the job is subsequently booked.

SS Field Mapping: Importance

Index

unsigned int

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.

SS Field Mapping: Index

ReqProvider

array

Allows for a list of up to 10 required employees to be specified, specifying any required MPX employee options.

Property

Type

Length

Description

Id

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

SS Field Mapping: listReqEmps.reqEmp[].empID

MPX

SS Field Mapping: listReqEmps.reqEmp[].MPX

Location

object

Property	Type	Length	Description
Latitude	double		The latitude of the location of the job, format length 18 with max 9 decimal places. If `postcode` is `UNKNOWN` then `latitude` and `longitude` are used to create a named place for the job. Such named places will not be visible on a ServicePlanner map. SS Field Mapping: latitude
Longitude	double		Is the longitude of the location of the job, format length 18 with max 9 decimal places. If `postcode` is `UNKNOWN` then `latitude` and `longitude` are used to create a named place for the job. Such named places will not be visible on a ServicePlanner map. SS Field Mapping: longitude
Postcode	string	30	The full postal code of the location of the job. SS Field Mapping: postcode
Country	N/A	N/A	Not used in ServiceScheduling
SiteID	string	20	A Site Identifier. ServiceOptimizer will attempt to schedule jobs with the same `siteID`s: (a) consecutively, so that there is 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 Mapping: siteID

MaxOffers

integer

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.

SS Field Mapping: numReq

NumReqTypes

string

2

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.

SS Field Mapping: numReqType

OfferOptions

object

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.

Property	Type	Description
AllowEmpOT	boolean	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. SS Field Mapping: offerOptions.AllowEmpOT
ConsecShift	boolean	This option requests the use of consecutive shifts (as well as allowing contiguous shifts) for splitting long duration jobs SS Field Mapping: offerOptions.ConsecShift
ContigShift	boolean	This option requests the use of only contiguous shift time splits for long duration jobs. SS Field Mapping: offerOptions.ContigShift
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. SS Field Mapping: offerOptions.DupUseEmpID
NonConsecShift	boolean	Allows the use of non-consecutive shifts (as well as allowing contiguous and consecutive shifts) for splitting long duration jobs SS Field Mapping: offerOptions.NonConsecShift
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. SS Field Mapping: offerOptions.OfferTextCost
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. Note: For Long jobs this parameter is not used and `EmpId` is always returned within the offer response. SS Field Mapping: offerOptions.OfferTextEmpID
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. SS Field Mapping: offerOptions.SpareIgnVanStock
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. SS Field Mapping: offerOptions.useExtraDuration

PickupSize

integer

The amount of space occupied by equipment that will be loaded onto 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: pickupSize

Part

array of objects

See Spares Information for details of the <reqSpares> structure.

Booking APIs can have up to 5 <reqSpare> structures inside the <reqSpares> structure, each of which contains a SpareID and a quantity.

Spares substitutes can be supplied by concatenating up to 5 SpareIDs separated by a semicolon character (';').

Property	Type	Length	Description
VendorId
VendorName
Id	string	30	Part ID reqSpares[].spare
Type
Qty	integer		Part Quantity quantity

Product

object

PromSet

string

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.

SS Field Mapping: promSet

RankingCutoff

ReqUnit

object

Property Type Length Description

UnitType

string

8

If Final, specifies that the RUID field is an FRU ID, or, if DRU, specifies that RUID is a DRU ID.

SS Field Mapping: unitType

RUID

string

8

The name of an FRU or DRU (set of FRUs) that must provide the employee assigned to the job. The job must be located at a postcode that is mapped to the supplied FRU or DRU, whether or not any of the In-Tray options are true (see forceOptions).

SS Field Mapping: RUID

SearchProcedure

object

StartDate

DateTime

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.

SS Field Mapping: start.date + start.time

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

StdExtraDuration

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

SS Field Mapping: stdExtraDuration

WorkType

object

Property

Type

Length

Description

Name

JobTypeID (string)

30

The type of work to be performed.

SS Field Mapping: jobTypeID

WarrantyType

ServiceBroker 5

Appointment Search Object: ServiceScheduling

Analytics

Appointment Search Object Format

Appointment Search Object Properties

Related content