On This Page:

Related Pages:

The sp:JobUpdateRequest API method can be used to update a job's priority, importance, access hours and customer information.

Description

The sp:JobUpdateRequest API method allows a job’s priority, importance, access hours and customer information to be updated without the need for the job to be re-booked.

The changes allowed to a job's access hours are:

to use the existing access hours that overlap the operative day that the job is already scheduled on;
to use the existing access hours that overlap the operative day that the job is already scheduled on plus a single supplied closed period; or
to replace the existing access hours with one or more open access hours overrides.

If any of these changes are made to the job’s access hours, all of its existing other access hours will be permanently removed. If they are subsequently required, the job should be rebooked.

In all cases, the job’s existing ETA (and ETF if it’s a call-to-fix job) must lie within the resulting access hours, otherwise SP_ETA_OUTSIDE_ACC_HOURS (447) will be returned. The job is never moved as a result of a call to sp:JobUpdateRequest, so that it remains in a position in the schedule where it fits in with the other jobs. Allowing the ETA to be outside the supplied access hours would mean that the job would immediately be in jeopardy with no guarantee that it could be re-scheduled to be done within those access hours. In such a situation, the job should be re-booked to determine if it can be re-scheduled within the required access hours.

Definition

The definition of this API is:

Click here to expand...

Web Service			Type	Description	Req?	Val?
`<sp:JobUpdateRequest>`
	`<jobID>?</jobID>`		`JobID`	is the caller’s identifier of the job to be updated. It must exist in the database otherwise SP_JOBID_INVALID (1) is returned.
	`<priority>?</priority>`			is the new Priority the job should be given. If the parameter is not supplied, no change will be made to the related value.
	`<importance>?</importance>`			is the new Importance the job should be given. (Normally a ‘confirmed’ job’s Importance should be raised to make it less likely that the job will be deallocated.). If the parameter is not supplied, no change will be made to the related value.
	`<openAccHoursOvrs>`			These two fields, along with the UseAccHours Option (below) can optionally be used to make changes to the job’s Access Hours: 1) If UseAccHours is not set, OpenAccHoursOvrs and ClosedAccHoursOvr replace all of the job’s existing access hours (from both access hours patterns and existing access hours overrides). 2) If UseAccHours is set, ClosedAccHoursOvr can be supplied (a single closed period), the OpenAccHoursOvrs parameter must not be supplied, otherwise SP_OPT_USE_AH_INVALID (450) is returned. If the job’s existing ETA wouldn’t be within its resulting access hours, SP_ETA_OUTSIDE_ACC_HOURS (447) is returned. (There is no override.) ClosedAccHoursOvr takes precedence over existing and supplied open access hours. If this parameter is not supplied, no changes to access hours will be made as a result of this call. Both start and end must be specified.
		`<start>?</start>`		is the date-time at which the override starts.
		`<end>?</end>`		is the date time at which the override ends.
	`</openAccHoursOvrs>`
	`<closedAccHoursOvr>`
		`<start>?</start>`		is the date-time at which the override starts.
		`<end>?</end>`		is the date time at which the override ends.
	`</closedAccHoursOvr>`
	`<checkEmp>?</checkEmp>`			is the Operative that the job should already be allocated to. If it isn’t, SP_WRONG_EMP (492) is returned. If this check isn’t required, the field should be omitted
	`<customer>`
				is information about the customer that this job is for.( See section 4.4.3)
	`</customer>`
	`<options>`			See the "Offer/Book Options" for the definitions of the permitted `options` listed below. If both `FixToEmp` and `RemoveMandatory` are supplied, `SP_OPTION_COMBINATION_INVALID (159)` will be returned
		`<FixToEmp>?</FixToEmp>`
		`<UseAccessHours>?</UseAccessHours>`		The `UseAccHours` parameter is only valid if no `OpenAccHoursOvrs` are supplied. If `OpenAccHoursOvrs` are supplied and `UseAccHours` is set, the call will fail with return code `SP_OPT_USE_AH_INVALID (450)`.
		`<SetNotFixed>?</SetNotFixed>`
		`<SetUnEarmark>?</SetUnEarmark>`		If `SetUnEarmark` is set without `SetDispStatusBack` being set, `SP_OPTION_COMBINATION_INVALID (159)` will be returned.
		`<SetDispStatusBack>?</SetDispStatusBack>`		setDispStatusBack will cause the job’s dispatch status to be set to SPDS_Tentative. If unEarmark is also set and unearmark message will be dispatched if the job’s current status is Earmarked, Contacted, Travelling, or LoggedOn.
		`<SetConfirmed>?</SetConfirmed>`
		`<RemoveMandatory>?</RemoveMandatory>`		removeMandatory, will cause any previously specified mandatory operatives 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.
	`</options>`
`</sp:JobUpdateRequest>`

The times fields are local to what is specified in the tz_BJAPIIn database parameter. This can be configured such that the dates and times are local to the timezone of the region where the job is located (customer local) or local to the default timezone.

Return Structure

The API returns the standard return structure.

Return Codes

In addition to the Standard Return Codes, the possible Return Codes from this API are:

Click here to expand...

SP_OK (0)
SP_JOBID_INVALID (1)
SP_OUTSIDE_HORIZON (53)
SP_OPTIONS_INVALID (80)
SP_PRIORITY_INVALID (81)
SP_CUSTID_INVALID (95)
SP_CUSTNAME_INVALID (96)
SP_CUSTADD1_INVALID (97)
SP_CUSTADD2_INVALID (98)
SP_CUSTADD3_INVALID (99)
SP_CUSTADD4_INVALID (100)
SP_CONTACTNAME_INVALID (101)
SP_CUSTPHONE1_INVALID (102)
SP_CUSTPHONE2_INVALID (103)
SP_UNRESOURCED_JOB (148)
SP_OPTION_COMBINATION_INVALID (159)
SP_IMPORTANCE_INVALID (287)
SP_DST_TIME_INVALID (379)
SP_OPEN_ENDED_ACCHOURS_NOT_ALLOWED (391)
SP_DATETIMERANGESEQ_RANGES_NULL (431)
SP_OPENHOURSOVRTYPE_INVALID (433)
SP_OPENACCHOURSOVR_START_INVALID (434)
SP_OPENACCHOURSOVR_END_INVALID (435)
SP_OPENACCHOURSOVR_END_NOT_GT_START (436)
SP_CLOSEDACCHOURSOVR_START_INVALID (437)
SP_CLOSEDACCHOURSOVR_END_INVALID (438)
SP_CLOSEDACCHOURSOVR_END_NOT_GT_START (439)
SP_NO_ACCHOURS (443)
SP_ETA_OUTSIDE_ACC_HOURS (447)
SP_OPT_USE_AH_INVALID (450)
SP_PRIORITY_NO_COST (475)
SP_IMPORTANCE_NO_COST (476)
SP_JOB_IS_APPOINTMENT (477)
SP_WRONG_EMP (492)
SP_CLEARED_JOB (493)

The sp:JobUpdateRequest SOAP API can not be called for an Appointment: SP_JOB_IS_APPOINTMENT (477) will be returned.

The sp:JobUpdateRequest SOAP API can only be called for resourced Jobs except when only updating Customer, Priority and/or Importance: SP_UNRESOURCED_JOB (148) is returned.

It can also only be called for Jobs whose dispatch status isn’t Logged Off or Cleared: SP_CLEARED_JOB (493) is returned otherwise.

Browser not supported