Document toolboxDocument toolbox

Integration ServiceOptimizer Update Spares Stock SOAP API

Owned by Matthew Wren
Nov 24, 2022
1 min read

On This Page:

Related Pages:

The sp:UpdateSparesStockRequest API method can be used to update the quantity of spares held in an employee's vehicle.

Description

The sp:UpdateSparesStockRequest API method updates the quantities of spares held in an employee’s vehicle. The spares quantity passed is the current stock in the van - the start of day spares quantity is worked out from that plus the spares already used by the logged off or cleared jobs. If system parameter recalculate_next_day_stock is set to NO then this value is the daily replenished spare value for tomorrow. If set to YES then the spares left over from today are the start of day spare quantities for tomorrow.

The updated spares value is available for scheduling jobs straight away (without the need for system restart).

Once spares are updated, the schedule is refreshed for all operatives who are part of the SOAP API request. (Job spares may be re-allocated and may have their source changes from Van to External or External to Van. However, work items on the schedule will not be moved by the stock refresh.)

Definition

The definition of this API is:

 Click here to expand...

Web Service

Type

Description

Req?

Val?

<sp:UpdateSparesStockRequest>

 

 

 

 

 

<NumLocs>?</NumLocs>

int

Optional. If not supplied, any number of <spareStock> structures may be passed in.

For backwards compatibility, if this field is supplied, the value must match the number of structures in the request, and must be <= 30, otherwise, SP_NUMLOCS_INVALID (180) will be returned.

(error)

 

 

<!-- Zero or more repetitions: -->

 

A list of spareStocks for an employee - only spares whose quantity has changed need to be sent; any spares not sent will keep their current quantity.

To remove a spare, send it with a quantity=0.

 

 

 

<spareStock>

 

 

(error)

 

 

 

<spareID>?</spareID>

SpareID

Identifier for the spare.

If the spareID is unknown, this API will add it to the list of known spares, as well as updating the spare stock, but if this spareID has already been used for a skill or special resource then SP_DUPLICATE_RESOURCE (803) will be returned.

Error SP_SPAREID_DUPLICATED (578) will be returned if a spareID is passed more than once.

(tick)

(tick)

 

 

<LocType>?</LocType>

LocType

The location of the spare. Currently, only the Vehicle value is supported, and is the default.

(error)

 

 

 

<spareLoc>?</spareLoc>

EmpID

The EmployeeID. If it is not valid or does not exist, SP_EMPID_DOES_NOT_EXIST (231) will be returned.

If an EmployeeID is passed who is located in an FRU that is not running then SP_FRU_UNAVAILABLE (259) will be returned. The update will only succeed if all employee spares records can be updated.

(tick)

(tick)

 

 

<quantity>?</quantity>

int

The quantity of the stock currently held by the employee (in the van). The maximum permitted value is 999,999.

The start of day spares stock value is extrapolated from this and the jobs already done by the employee using spares (Cleared and LoggedOff jobs). The maximum value of the extrapolated quantity is also 999,999 and if the stock quantity passed here would make the extrapolated value exceed this value then SP_QUANTITY_INVALID (112) will be returned.

(tick)

 

 

</spareStock>

 

 

 

 

</sp:UpdateSparesStockRequest>

 

 

 

 

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:

  • SP_OK (0)
  • SP_EMPID_INVALID (5)
  • SP_QUANTITY_INVALID (112)
  • SP_NUMLOCS_INVALID (180)
  • SP_SPAREID_DUPLICATED (578)
  • SP_DUPLICATE_RESOURCE (803)