On This Page:

Related Pages:

The sp:GetEmpRequest API method can be used to obtain the details of an employee.

Description

The sp:GetEmpRequest API method allows the details of an employee to be obtained.

Definition

The definition of this API is:

Click here to expand...

Web Service		Type	Description	Req?	Val?
`<sp:GetEmpRequest>`
	`<empID>?</empID>`	`EmpID`	The ID of the employee for which the employee details are to be returned.
	`<FRU-postings>?</FRU-postings>`	`boolean`	Optional parameter. When supplied and `true`, response body will include the FRU postings for the employee.
`</sp:GetEmpRequest>`

Return Structure

The API returns a non-standard return structure.

Click here to expand...

Web Service				Type	Description	Req?	Val?
`<sp:GetEmpResponse>`
	`<result>`				A structure containing details of the success or failure of the API call.
		`<type>?</type>`		`string`	The Return Code name, representing the result of the API call.
		`<code>?</code>`		`int`	The Return Code number, representing the result of the API call.
	`</result>`
	`<attr>`				A optional structure containing the employee's details. This structure is only returned when the API call does not return an error Return Code.
		`<type>?</type>`		`int`	The employee type: When `0`, the employee is a individual employee; When `1`, the employee is actually a crew (team) of employees.
		`<name>?</name>`		`string`	The employee's name, as generally to be displayed in a system UI.
		`<surname>?</surname>`		`string`	The employee's surname only, as generally to be used in sorting of employees.
		`<job-title>?</job-title>`		`string`	The employee's job title.
		`<efficiency>?</efficiency>`		`int`	The employee's efficiency rating, as a percentage value.
		`<address1>?</address1>`		`string`	The first line of the employee's home address.
		`<address2>?</address2>`		`string`	The second line of the employee's home address.
		`<address3>?</address3>`		`string`	The third line of the employee's home address.
		`<address4>?</address4>`		`string`	The fourth line of the employee's home address.
		`<postcode>?</postcode>`		`string`	The employee's home address ZIP code/postcode.
		`<region-no>?</region-no>`		`int`	The ID of the "region" in which the employee's home address is located.
		`<region-ref>?</region-ref>`		`string`	The reference value of the "region" in which the employee's home address is located.
		`<phone1>?</phone1>`		`string`	The employee's primary telephone number.
		`<phone2>?</phone2>`		`string`	The employee's secondary telephone number.
		`<pager>?</pager>`		`string`	The employee's pager number.
		`<hand-held1>?</hand-held1>`		`string`	A customer-defined string representing the "address" of the employee's primary hand-held device.
		`<hand-held2>?</hand-held2>`		`string`	A customer-defined string representing the "address" of the employee's secondary hand-held device.
		`<current-hand-held>?</current-hand-held>`		`string`	A customer-defined string representing which of the employee's hand-held devices is currently in use.
		`<schedulable>?</schedulable>`		`int`	A flag indicating whether or not the employee can be scheduled jobs: `0` - The employee is not schedulable `1` - The employee is schedulable
		`<max-overtime>?</max-overtime>`		`int`	The maximum number of minutes authorised overtime that the employee can work in any one shift period.
		`<printer>?</printer>`		`string`	A customer-defined string representing the "print location" for the employee.
		`<inform-lead-time>?</inform-lead-time>`		`int`	The inform lead time, in minutes, for this employee, if one has been defined. In the event that one has not been defined for the employee, then no value will be returned. However, please be aware that in this case, the system will be using either: the inform lead time for the employee's responsibility unit (recorded in the `sp213_scheduler_parameters` database table), or, if this is `NULL`; then the system inform lead time (recorded in the `sp083_system_parameters` database table).
		`<work-region-no>?</work-region-no>`		`int`	A reference to a location in the `sp047_postcodes` database table, where the value of `sp047_postcodes.region_no` is equal to the value of `work-region-no`. The reference define's the employee's "work" location, to be used when appropriate for: Their start of shift location (see the `default-start-loc` field); Their end of shift location (see the `default-end-loc` field); or Their local knowledge calculation location (see the `default-lk-centre-loc` field).
		`<work-postcode>?</work-postcode>`		`string`	The employee's "work" location ZIP code/postcode, matching the location referenced by the `work-region-no` field above.
		`<tz-type>?</tz-type>`		`int`	An employee may, through a working day, move between different time zones. The employee's schedule for the day could be represented in terms of the time zone of the location in which they are in at any given time, but it is more sensible to assume that the employee has a watch and is working to their own "local" time zone. The `tz-type` flag indicates how the employee's "local" time zone is determined: `0` - The employee's "local" time zone will be determined by the value of the `tz_no` field. `1` - The employee's "local" time zone will be determined by the employee's home address. Otherwise, if the field is `NULL`, the employee's "local" time zone will be determined by the `tz_Default` value of the `sp083_system_parameters` database table.
		`<tz-no>?</tz-no>`		`int`	When the `tz-type` field (above) is set to `0:` If `tz-no` is `NULL`, then the server's time zone is used for the employee's "local" time zone; otherwise The employee's "local" time zone is the timezone stored in the `sp056_time_zones` database table, where the value of `sp056_time_zones.tz_no` is equal to the value of `tz-no`.
		`<earmarked-jobs-max>?</earmarked-jobs-max>`		`int`	The maximum number of jobs that will be auto-earmarked at any given time for the employee. The count only applies to jobs that are auto-eamarked. Those earmarked by batch dispatch or user-earmarked do not count towards `earmarked_jobs_max`. `O`nce a job is no longer earmarked, e.g. it has passed on into the contacted state, it also no longer counts towards `earmarked_jobs_max`. If the field is `NULL`, then the maxmimum number of jobs that will be auto-earmarked at any given time for the employee will be determined by the `disp_earmark_jobs_max` value set in the `sp213_scheduler_parameters` database table (if present for the employee's RU), or, otherwise, by the `disp_earmark_jobs_max` value of the `sp083_system_parameters` database table.
		`<default-start-loc>?</default-start-loc>`		`string`	The location of the employee at the start of their shift: `0` - Home `1` - Work `2` - Depot `3` - Specified
		`<default-start-loc-postcode>?</default-start-loc-postcode>`		`string`	The ZIP code/postcode of the employee's start of shift location, when the value of the `default-start-loc` field is `3` (Specified).
		`<default-start-loc-region-no>?</default-start-loc-region-no>`		`int`	The ID of the employee's start of shift location "region", when the value of the `default-start-loc` field is `3` (Specified).
		`<default-end-loc>?</default-end-loc>`		`string`	The location of the employee at the end of their shift: `0` - Home `1` - Work `2` - Depot `3` - Specified
		`<default-end-loc-postcode>?</default-end-loc-postcode>`		`string`	The ZIP code/postcode of the employee's end of shift location, when the value of the `default-end-loc` field is `3` (Specified).
		`<default-end-loc-region-no>?</default-end-loc-region-no>`		`int`	The ID of the employee's end of shift location "region", when the value of the `default-end-loc` field is `3` (Specified).
		`<totb>?</totb>`		`int`	The maximum permitted before-shift travel for the employee, in minutes. When `NULL`, this indicates that the maximum permitted before-shift travel value for the employee will be the value defined for the employee's FRU.
		`<tota>?</tota>`		`int`	The maximum permitted after-shift travel for the employee, in minutes. When `NULL`, this indicates that the maximum permitted after-shift travel value for the employee will be the value defined for the employee's FRU.
		`<default-lk-centre-loc>?</default-lk-centre-loc>`		`string`	The location from which the employee's Local Knowledge range is calculated: `0` - Home `1` - Work `2` - Depot `3` - Specified
		`<default-lk-centre-postcode>?</default-lk-centre-postcode>`		`string`	The ZIP code/postcode of the employee's Local Knowledge range calculation location, when the value of the `default-lk-centre-loc` field is `3` (Specified).
		`<default-lk-centre-region-no>?</default-lk-centre-region-no>`		`int`	The ID of the employee's Local Knowledge range calculation location "region", when the value of the `default-lk-centre-loc` field is `3` (Specified).
		`<vehicle-capacity>?</vehicle-capacity>`		`int`	The total amount of space available in the employee's vehicle for pickups and deliveries, in user-defined units.
		`<frozen-lead-days>?</frozen-lead-days>`		`string`	The number of days, starting from "today", that should be frozen for the employee. If this value is `0` then "today" does not get frozen until "now" is later than the value of `frozen-day-trigger-time`. If this value is `1` then "today" will be frozen, and "tomorrow" will be frozen once it is later than the value of `frozen-day-trigger-time` – and so on. Takes account of non-working days (see: `sp013_non_working_days`).
		`<frozen-day-trigger-time>?</frozen-day-trigger-time>`		`int`	This is an `HHMM` formatted value (no hours/minutes separator) that represents the time at which the appropriate day should be frozen. The time is determined by appending this time to today's date, and is interpreted to be in the employee "local" time.
		`<show-operative-status>?</show-operative-status>`		`int`	A flag field that defines how the employee's status will be displayed in ServiceScheduling. When the value is: `0` - Neither the employee's status or travel status is displayed; `1` - Only the employee's status is displayed; `2` - Only the employee's travel status is displayed; `3` - Both the employee's status and the travel status are displayed.
		`<travel-status>?</travel-status>`		`int`	The employee's current travel status as set by an Update Travel Status SOAP API call. Typically this is the status reported to ServiceOptimizer that represents the vehicle's current state: `0` - None `2` - Stopped `3` - Stationary `4` - Moving `5` - Unknown. If travel status is not enabled for this employee or this employee has not yet had a travel status supplied via the API, then the value will be `0`.
		`<travel-status-time>?</travel-status-time>`		`string`	The date/time (in the employee's FRU timezone) that the employee's `travel-status` value was set by an Update Travel Status SOAP API call, for the last such API call made. Note: This is the date and time at which the call to the Update Travel Status SOAP API was made - not the `timeStamp` field supplied as one of the Update Travel Status SOAP API call parameters.
		`<travel-api-time>?</travel-api-time>`		`string`	The date/time (in the employee's FRU timezone) that the employee's `travel-status` value was set according to the `timeStamp` field supplied as one of the Update Travel Status SOAP API call parameters, for the last such API call made.
		`<last-moving-time>?</last-moving-time>`		`string`	The most recent date/time (in the employee's FRU timezone) that the employee's `travel-status` value was set to the `Moving` status, according to the `timeStamp` field supplied as one of the Update Travel Status SOAP API call parameters, for the last such API call made.
		`<current-loc-type>?</current-loc-type>`		`string`	If the current `travel-status` value is `2` (i.e. Stopped) then the `current-loc-type` value further qualifies the type of location at which the employee is stopped (see `sp561_geofence_location_types`).
		`<geo-fence-name>?</geo-fence-name>`		`string`	The descriptive name of the employee's current location, if present, as taken from the `geoFence.name` field supplied as one of the Update Travel Status SOAP API call parameters, for the last such API call made.
		`<last-stopped-ok>?</last-stopped-ok>`		`string`	The date/time (in the employee's FRU timezone) that the employee's travel status was last known to be stopped at a location in the "stopped OK" class (see `sp561_geofence_location_types.location_class`).
		`<last-stopped-overnight>?</last-stopped-overnight>`		`string`	The date/time (in the employee's FRU timezone) that the employee's travel status was last known to be stopped at a location in the "overnight" class (see `sp561_geofence_location_types.location_class`).
		`<last-stopped-customer>?</last-stopped-customer>`		`string`	The date/time (in the employee's FRU timezone) that the employee's travel status was last known to be stopped at a location in the "customer" class (see `sp561_geofence_location_types.location_class`).
		`<FRU-postings>`			An optional structure only returned if the `FRU-postings` field in the input call is set to `true`.
			`<FRU>?</FRU>`	`string`	A string representing the FRU that the employee is posted to. Multiple instances of this field may be returned if the employee is posted to multiple FRUs.
		`</FRU-postings>`
	`</attr>`
`</ssp:GetEmpResponse>`

Return Codes

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

Click here to expand...

SP_EMPID_INVALID (5)

Browser not supported