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": "",
	"EndDate": "",
	"ExtraDuration": "",
	"ExtraOverhead": "",
	"ExtraSkills": [
		{
			"SkillID": "",
			"SkillLevel": "",
			"Mfg": "",
			"ProdLine": "",
			"ServiceType": "",
			"WarrantyType": ""
		},
		...
	],
	"ForceOptions": {
		"IgnoreCapacity": "",
		"IgnoreOverlap": "",
		"InTray": "",
		"InTrayWithSkill": "",
		"NoLocalKnowledge": "",
		"NoTravel": "",
		"Reassign": "",
		"SpareForceGo": ""
	},
	"GroupID": "",
	"Importance": "",
	"Index": "",
	"ReqProvider": [
		{
			"Id": "",
			"MPX": ""
		},
		...
	],
	"Location": {
		"Latitude": "",
		"Longitude": "",
		"Postalcode": "",
		"Country": "",
		"SiteID": ""
	},
	"MaxOffers": "",
	"NumReqType": "",
	"OfferOptions": {
		"AllowEmpOT": "",
		"ConsecShift": "",
		"ContigShift": "",
		"DupUseEmpID": "",
		"NonConsecShift": "",
		"OfferTextCost": "",
		"OfferTextEmpID": "",
		"SpareIgnVanStock": "",
		"UseExtraDuration": ""
	},
	"PickupSize": "",
	"PreferredDate": "",
	"Part": [
		{
			"VendorId": "",
			"VendorName": "",
			"Id": "",
			"Type": "",
			"Qty": ""
		},
		...
	],
	"Product": {
		"Mfg": "",
		"ProdLine": ""
	},
	"PromSet": "",
	"RankingCutoff": "",
	"ReqUnit": {
		"RUID": "",
		"UnitType": ""
	},
	"SearchProcedure": {
		"ProcedureCode": "",
		"ElementAttributes": [
			{
				"Name": "",
				"Value": ""
			},
			...
		]
	},
	"StartDate": "",
	"SortBy": "",
	"StdExtraDuration": "",
	"WarrantyType": "",
	"WorkType": {
		"Name": ""
	}	
}

Appointment Search Object Properties

Field Mappings

REST Work Item Appointment Search calls may result in an appointment search request being directed to either a ServiceDispatch system, a ServiceScheduling system, or both. (See the REST Work Item Appointment Search definition for details on how this is configured).

As a result, all of the fields in the Appointment Service Object are passed through to ServiceDispatch and/or ServiceScheduling, which means that the field definitions depend on the API that they are passed to.

In addition, fields may, or may not be, mandatory, depending on the system(s) to which they are passed, with the exception of some fields which are mandated by ServiceBroker itself (and which are marked below).

ServiceDispatch Field Mappings

When an REST Work Item Appointment Search call results in an appointment search request being directed to ServiceDispatch, the fields that are present in the Appointment Search Object (below) with a ServiceDispatch field mapping will be passed to ServiceDispatch.

As a result, the definition of these fields depends on how ServiceDispatch handles the fields.

Please speak with the ServicePower customer services team for the field definitions.

ServiceScheduling Field Mappings

When an REST Work Item Appointment Search call results in an appointment search request being directed to ServiceScheduling, the fields that are present in the Appointment Search Object (below) with a ServiceScheduling field mapping will be passed to ServiceScheduling.

As a result, the definition of these fields depends on how ServiceScheduling handles the fields.

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

Property				Type	Length	Description	Field Mappings
Property				Type	Length	Description	ServiceDispatch	ServiceScheduling
`Band`				`object`	No	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 Below	See Below
	`Start`			string	4	See above.	N/A	`band.start`
	`End`			string	4	See above.	N/A	`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.	N/A	`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.	N/A	`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).	N/A	`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	N/A	`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. 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'	`(End.Date+Time - Start.Date+Time) --> SearchProcedure.NoDays`	`end.date + end.time`
`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.	`SearchProcedure.JobDuration`	`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.	N/A	`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.	See below	See below
		`SkillID`			-	-	N/A	`extraSkills.reqSkills[].skillID`
		`SkillLevel`			varied, see discription	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`	N/A	`extraSkills.reqSkills[].skillLevel`
		`Mfg`			-	-	`ExtraSkills.BrandCode`	N/A
		`ProdLine`			-	-	`ExtraSkills.ProductCode`	N/A
		`ServiceType`			-	-	`ExtraSkills.ServiceType`	`ExtraSkills.ProductCode`
		`WarrantyType`			-	-	`ExtraSkills.WarrantyType`	N/A
`ForceOptions`				`object`	-	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)`.	See: Force Options	See: Force Options
	`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.	N/A	`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)`.	N/A	`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.	N/A	`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.	N/A	`forceOptions.InTrayWithSkill`
	`NoLocalKnowledge`			boolean		Ignores local knowledge checks in candidate searches.	N/A	`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.	N/A	`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`.	N/A	`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.	N/A	`forceOptions.SpareForceGo`
`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.	N/A	`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.	N/A	`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`.	N/A	`index`
`ReqProvider`				`array`		Optional array, containing one or more field container objects.	See below	See beliw
		`Id`				Defined a preferred, mandatory or excluded operative for the job.	`MulPrefServiceCenter[]` `PrefServiceCenterID`	`listReqEmps.reqEmp[].empID`
		`MPX`				-	N/A	`listReqEmps.reqEmp[].MPX`
`Location`				`object`		Mandatory field container object.	See below	see beloq
	`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.	N/A	`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.	N/A	`longitude`
	`Postalcode`			string	30	The full postal code of the location of the job.	`ProductLocation.Postcode`	`postcode`
	`Country`				-	The physical country where the job is located.	`ProductLocation.Country`	N/A
	`SiteID`				-	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.	`ProductLocation.SiteID`	`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 `PromTypeID`s 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`	`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.	N/A	`numReqType`
`OfferOptions`				`object`	No	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.	See below	See below
	`AllowEmptOT`			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.	`offerOptions.AllowEmpOT`	offerOptions.AllowEmpOT
	`ConsecShift`			boolean	-	This option requests the use of consecutive shifts (as well as allowing contiguous shifts) for splitting long duration jobs	`offerOptions.ConsecShift`	offerOptions.ConsecShift
	`ContigShift`			boolean	-	This option requests the use of only contiguous shift time splits for long duration jobs.	`offerOptions.ContigShift`	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.	`offerOptions.DupUseEmpID`	offerOptions.DupUseEmpID
	`NonConsecShift`			boolean	-	Allows the use of non-consecutive shifts (as well as allowing contiguous and consecutive shifts) for splitting long duration jobs	`offerOptions.NonConsecShift`	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.	`offerOptions.OfferTextCost`	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.	`offerOptions.OfferTextEmpID`	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.	`offerOptions.SpareIgnVanStock`	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.	`offerOptions.useExtraDuration`	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.	N/A	`pickupSize`
`PreferredDate`					-	-	N/A	`preferredDate`
`Part`				`array`	No	Optional array, containing one or more field container objects.	See below	See below
		`VendorId`		String	-	The ID of the vendor that part comes from.	`PartInfo.ItemVendor`
		`VendorName`		String	-	The name of the vendor that supplies the part.	`PartInfo.ItemVendorName`
		`Id`		string	30	The ID of the part.	`PartInfo.PartId`
		`Type`				The clssification of the part.	`PartInfo.PartType`
		`Qty`		integer		The number of the parts ordered.	N/A
`Product`				`object`	No	Optional field container object.
	`Mfg`				-	-	`ProductInfo.BrandCode`
	`ProdLine`				-	-	`ProductInfo.ProductCode`
`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.	N/A	`promSet`
`RankingCutoff`					-	-	`RankingCutoff`
`ReqUnit`				`object`	object	Optional field container object.
	`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`).	N/A	`reqUnit.RUID`
	`UnitType`			string	8	If `Final`, specifies that the `RUID` field is an FRU ID, or, if `DRU`, specifies that `RUID` is a DRU ID.	N/A	`reqUnit.unitType`
`SearchProcedure`				`object`		Optional field container object.
	`ProcedureCode`					-	`SearchProcedure.ProcedureCode`
	`ElementAttributes`			array	?	Optional array, containing one or more field container objects.	`SearchProcedure.ElementAttributes`
			`Name`		?	-	`SearchProcedure.ElementAttributes[].Name`
			`Value`		>	-	`SearchProcedure.ElementAttributes[].Value`
`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`. 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'	`SearchProcedure.StartDate`	`start.date + start.time`
`SortBy`						-	`SortBy (Rank - Servicer-Ranking, Date)`
`StdExtraDuration`				StdExtraDuration		Specially defined extra time added to the normal amount for the job type. This time is specified in the DB.	N/A	`stdExtraDuration`
`WarrantyType`						-	`WarrantyType`	N/A
`WorkType`				`object`	30	Mandatory field container object.
	`Name`			JobTypeID (string)	Yes	The type of work to be performed.	`ServiceType`	`jobType`

Browser not supported