_API ApptOfferRequest Definition

<sp:ApptOfferRequest>

<numReq>?</numReq>

unsigned int

<numReqType>?</numReqType>

PromTypeID

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.

<index>?</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.

<jobType>?</jobType>

JobTypeID

The type of work to be performed.

<postcode>?</postcode>

Postcode

The full postal code of the location of the job.

<latitude>?</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.

<longitude>?</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.

<vwdlLocationType>?</vwdlLocationType>

<promSet>?</promSet>

PromSetID

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.

<extraDuration>?</extraDuration>

unsigned int

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.

<extraOverhead>?</extraOverhead>

unsigned int

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.

<extraSkills>

A list of the extra skills needed to do this job, in addition to those specified in ServiceOptimizer for the job's type. If one or more of the supplied extraSkills is already required by the JobType, it will be ignored, unless it is the first extraSkill and the skillLevel (below) is different from that specified for the JobType. 

The maximum number of skills that can be supplied is 10; however, only the skillLevel for the first skillID in the list has any meaning; other skills are assumed to require no specific level.

<reqSkills>

<skillID>?</skillID>

SkillID

<skillLevel>?</skillLevel>

unsigned int

The level of the extra skill required in the skillID field, above. If the first of the skillIDspecifies 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.

</reqSkills>

</extraSkills>

<ListReqEmps>

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

<reqEmp>

<empID>?</empID>

EmpID

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

<MPX>?</MPX>

</reqEmp>

</ListReqEmps>

If true return the Schedule Cost Breakdown structure details as part of the response.

If either the forceOptions InTray or InTrayWithSkill options are set to true, then the Schedule Cost Breakdown structure will not be returned in the response.

<stdExtraDuration>?</stdExtraDuration>

StdExtraDuration

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

<reqUnit>

<unitType>?</unitType>

UnitType

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

<RUID>?</RUID>

RUID

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

</reqUnit>

<days>?</days>

DayOfTheWeek

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

<start>

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.

<date>?</date>

spDate

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

<time>?</time>

Time

If not supplied, ServiceOptimizer will use a default of 0000 on the start date (above), or <now> if the start date is <today>.

</start>

<end>

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

<date>?</date>

spDate

If not supplied, ServiceOptimizer will use a default of the start date (above) plus the Appointment Booking Horizon (see abs_appt_days_after).

<time>?</time>

Time

If not supplied, ServiceOptimizer will use a default of 2400 on the end date.

</end>

<preferredDate>?</preferredDate>

spDate

Defines the date of the appointments which should be returned first. If preferredDate is outside the date range defined by the start and end date parameters, additional appointments may be returned, even if the start date value has been defaulted using the Booking Lead Time (as described above).

Note: When requesting appointments for long duration jobs, that are to be split across multiple shifts, the preferredDate parameter must not be supplied; supplying the parameter will result in inconsistent results.

<band>

The band parameters timeBandID, start, and end values are used to generate a notional filter band, FilterStartTime to FilterEndTime.

The FilterStartTime is set to:

• The value of start, if supplied; or, if not
• The timeBandID's StartTime, if timeBandID is supplied; or, if not
• The start of the day.

Similarly, the FilterEndTime is set to:

• The value of end, if supplied; or, if not
• The timeBandID's EndTime, if timeBandID is supplied; or, if not
• The end of the day.

As jobs can span midnight, the FilterEndTime can appear to be before FilterStartTime, but this is interpreted as being on the next day.

• If the filter band is totally outside the initially-generated offer (i.e. there is no overlap between them), the offer is not returned at all.
• If FilterStartTime is within an offered appointment, i.e. is between the initially-generated values of PromStartTime and PromEndTime (see later in this section), then PromStartTime will be changed to FilterStartTime before returning that offer.
• Similarly, if FilterEndTime is within the appointment, then PromEndTime will be changed to FilterEndTime.

Note: An initially-generated offer can never be lengthened by application of the filter band, only shortened.

<timeBandID>?</timeBandID>

TimeBandID

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.

<start>?</start>

Time

<end>?</end>

Time

</band>

<importance>?</importance>

int

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.

<offerOptions>

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

<AllowEmpOT>?</AllowEmpOT>

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.

<OfferTextEmpID>?</OfferTextEmpID>

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

<DupUseEmpID>?</DupUseEmpID>

<SpareIgnVanStock>?</SpareIgnVanStock>

<OfferTextCost>?</OfferTextCost>

<NonConsecShift>?</NonConsecShift>

<ConsecShift>?</ConsecShift>

<ContigShift>?</ContigShift>

<UseFRUFilter>?</UseFRUFilter> 

<forceOptions>

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

<InTray>?</InTray>

<InTrayWithSkill>?</InTrayWithSkill>

<SpareForceGo>?</SpareForceGo>

<Reassign>?</Reassign>

<IgnoreCapacity>?</IgnoreCapacity>

<NoTravel>?</NoTravel>

<NoLocalKnowledge>?</NoLocalKnowledge>

</forceOptions>

<reqSpares>

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

</reqSpares>

<deliverySize>?</deliverySize>

int

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.

<pickupSize>?</pickupSize>

int

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.

<siteID>?</siteID>

SiteID

A Site Identifier. ServiceOptimizer will attempt to schedule jobs with the same siteIDs: (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.

<groupID>?</groupID>

GroupID

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.

<capacityCategory>?</capacityCategory>

CapacityCategoryName

Capacity constraints, in the form of a reserved or/and limit level can be defined for each capacityCategory and a check can be done in the sp:ApptOfferRequest API so that only those offers where none of these constraints would be broken are returned. This parameter, if used, contains the name of the Capacity Category to which this Job belongs; 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.