On This Page:

Related Pages:

The sp:GetChangedEmpRequest API method can be used to store external data related to an operative, so that it can be managed using ServiceManager.

Description

It is possible to capture, and store, external data against an operative so that this data can then be managed using ServiceManager as a single point of update, if so desired. Data types are presented as ‘external data objects’ providing a grouping of ‘external data attributes’.

Each data object defines:

An identifier
A display name
The FRU(s) where this object may be populated

Each data attribute defines:

an identifier (note that this must be unique across the system, and not just unique to the object it belongs to)
a display name
a display sequence (to order the list in the operative screens)
the object it belongs to
a value type (integer, float, string, Boolean)
an optional mapping to a defined ServiceOptimizer operative attribute (one of the SPESDT values, see below)
an optional default value
a numeric minimum value (for integer/float types)
a numeric maximum value (for integer/float types)
a maximum number of decimal places (for float types)
a maximum number of characters (for string types)
the string value for true (for Boolean types) e.g. ‘On’, ‘Yes’, ‘True’
a string value for false (for Boolean types) e.g. ‘Off’, ‘No’, ‘False’
whether the data type is mandatory or optional

The available mappings to defined ServiceOptimizer attributes are as follows:

`SPESDT` Value	ServiceOptimizer Attribute Used	Type
`SPESDT_Specified`	Use `<value>`	Free text, whatever was input over the interface
`SPESDT_EmpID`	Use `EmployeeRef`	25 character string- alphanumeric unique identifier
`SPESDT_Name`	Use `Name`	50 character string- this is full name i.e. first name and surname together, separated by spaces
`SPESDT_Surname`	Use `Surname`	50 character string
`SPESDT_HomePostcode`	Use `HomePostcode`	30 character string- in the US this is typically either a 5 digit zip or the zip+4
`SPESDT_WorkPostcode`	Use `WorkPostcode`	30 character string- in the US this is typically either a 5 digit zip or the zip+4
`SPESDT_Address1`	Use `Address1`	50 character string – alphanumeric including spaces and other characters
`SPESDT_Address2`	Use `Address2`	50 character string – alphanumeric including spaces and other characters
`SPESDT_Address3`	Use `Address3`	50 character string – alphanumeric including spaces and other characters
`SPESDT_Address4`	Use `Address4`	50 character string – alphanumeric including spaces and other characters
`SPESDT_Phone1`	Use `Phone1`	40 character string
`SPESDT_Phone2`	Use `Phone2`	40 character string
`SPESDT_Pager`	Use `Pager`	20 character string
`SPESDT_WorkTZ`	Use `WorkTZ`	50 character string - the format for this is a full TZ value e.g. AST-10ADT,M10.5.0,M3.5.0
`SPESDT_Team`	Use `Team`	40 character string
`SPESDT_FRU`	Use `FRU`	8 character string
`SPESDT_Depot`	Use `Depot`	20 character string

These external data objects and attributes can be updated via ServiceManager, or via the Create Operative SOAP API and the Update Operative SOAP API.

External data that has been created, updated or removed for an operative can then be retrieved by using the sp:GetChangedEmpRequest interface.

Definition

The definition of this API is:

Click here to expand...

Web Service			Type	Description	Req?	Val?
`<sp:GetChangedEmpRequest>`
	`<lastExtractTime>?</lastExtractTime>`			date/time to start the search for updates. If this is null, then ALL of the operatives in the database will be extracted.
	`<teams>?</teams>`			select only operatives who have a posting to the specified Team(s) within the extract period (See note 1)
	`<FRUs>?</FRUs>`			select only operatives who have a posting to the specified FRU(s) within the extract period (See Note 1)
	`<lastExtractedEmpID>?</lastExtractedEmpID>`		`EmpID`	start the extract from the operative after this (for use after error)
	`<requiredObjects>?</requiredObjects>`			list of external data objects required in the return
	`<options>`			currently unused but allows for future extensions to behaviour
		`<unused>?</unused>`
	`</options>`
`</sp:GetChangedEmpRequest>`

Notes:

if both FRU and Team are null select all

The ‘added’ case will return all requested external objects that the operative has defined if the operative has been created since the lastExtractTime, or if an operative who previously had his/her final posting ended has been given () a new posting that means that operative is once again a ‘current’ posting.

‘Update’ records will only be sent if changes have been applied, to either the external data attributes themselves or to the ServiceOptimizer attributes they reference, since the lastExtractTime. For any requested object a change to any of the attributes will mean that all attributes will be returned, however each will have a ‘modified’ Boolean so that the caller knows which have been changed within the extract timeframe.

When an external data object is requested, if an operative has some of the external data attributes for that object defined, but not all of them, then only the attributes where the operative has a defined value will be returned. If an operative has no attributes for a particular object defined then the object is not returned for that operative (but there may be other objects returned if the request specified multiple objects)

For deletion records, these will be sent when an operative’s final posting has an end date added, and that end date now falls inside the time period defined by lastExtractTime.

Return Structure

The API returns a non-standard return structure.

Click here to expand...

Web Service				Type	Description	Req?	Val?
`<sp:GetChangedEmpResponse>`
	`<result>?</result>`
	`<totalRecords>?</totalRecords>`				total number of records
	`<numRecords>?</numRecords>`				number in this response (will be < total if lastExtractedEmpID is used)
	`<Emps>`
		`<empID>?</empID>`		`EmpID`
		`<recordType>?</recordType>`			defines whether the rest of the record defines an added, updated or deleted operative.
		`<externalObject>`
		`<name>?</name>`
		`<externalData>`
			`<name>?</name>`
			`<value>?</value>`
			`<modified>?</modified>`
			`</externalData>`
		`</externalObject>`
	`</Emps>`
`</sp:GetChangedEmpResponse>`

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_EMPID_INVALID (5)
SP_OPTIONS_INVALID (80)
SP_TEAMID_INVALID (200)
SP_EMPID_DOES_NOT_EXIST (231)
SP_TEAMID_DOES_NOT_EXIST (249)
SP_FRUID_INVALID (278)
SP_FRUS_AND_TEAMS_BOTH_SUPPLIED (316)
SP_DATETIME_INVALID (538)
SP_FRUID_DOES_NOT_EXIST (636)
SP_EXTERNAL_NAME_INVALID (659)

Description

It is possible to capture, and store, external data against an operative so that this data can then be managed using ServiceManager as a single point of update, if so desired. Data types are presented as ‘external data objects’ providing a grouping of ‘external data attributes’.

Each data object defines:

An identifier
A display name
The FRU(s) where this object may be populated

Each data attribute defines:

an identifier (note that this must be unique across the system, and not just unique to the object it belongs to)
a display name
a display sequence (to order the list in the operative screens)
the object it belongs to
a value type (integer, float, string, Boolean)
an optional mapping to a defined ServiceOptimizer operative attribute (one of the SPESDT values, see below)
an optional default value
a numeric minimum value (for integer/float types)
a numeric maximum value (for integer/float types)
a maximum number of decimal places (for float types)
a maximum number of characters (for string types)
the string value for true (for Boolean types) e.g. ‘On’, ‘Yes’, ‘True’
a string value for false (for Boolean types) e.g. ‘Off’, ‘No’, ‘False’
whether the data type is mandatory or optional

The available mappings to defined ServiceOptimizer attributes are as follows:

`SPESDT` Value	ServiceOptimizer Attribute Used	Type
`SPESDT_Specified`	Use `<value>`	Free text, whatever was input over the interface
`SPESDT_EmpID`	Use `EmployeeRef`	25 character string- alphanumeric unique identifier
`SPESDT_Name`	Use `Name`	50 character string- this is full name i.e. first name and surname together, separated by spaces
`SPESDT_Surname`	Use `Surname`	50 character string
`SPESDT_HomePostcode`	Use `HomePostcode`	30 character string- in the US this is typically either a 5 digit zip or the zip+4
`SPESDT_WorkPostcode`	Use `WorkPostcode`	30 character string- in the US this is typically either a 5 digit zip or the zip+4
`SPESDT_Address1`	Use `Address1`	50 character string – alphanumeric including spaces and other characters
`SPESDT_Address2`	Use `Address2`	50 character string – alphanumeric including spaces and other characters
`SPESDT_Address3`	Use `Address3`	50 character string – alphanumeric including spaces and other characters
`SPESDT_Address4`	Use `Address4`	50 character string – alphanumeric including spaces and other characters
`SPESDT_Phone1`	Use `Phone1`	40 character string
`SPESDT_Phone2`	Use `Phone2`	40 character string
`SPESDT_Pager`	Use `Pager`	20 character string
`SPESDT_WorkTZ`	Use `WorkTZ`	50 character string - the format for this is a full TZ value e.g. AST-10ADT,M10.5.0,M3.5.0
`SPESDT_Team`	Use `Team`	40 character string
`SPESDT_FRU`	Use `FRU`	8 character string
`SPESDT_Depot`	Use `Depot`	20 character string

These external data objects and attributes can be updated via ServiceManager, or via the Create Operative SOAP API and the Update Operative SOAP API.

External data that has been created, updated or removed for an operative can then be retrieved by using the sp:GetChangedEmpRequest interface.

Definition

The definition of this API is:

Click here to expand...

Web Service			Type	Description	Req?	Val?
`<sp:GetChangedEmpRequest>`
	`<lastExtractTime>?</lastExtractTime>`			date/time to start the search for updates. If this is null, then ALL of the operatives in the database will be extracted.
	`<teams>?</teams>`			select only operatives who have a posting to the specified Team(s) within the extract period (See note 1)
	`<FRUs>?</FRUs>`			select only operatives who have a posting to the specified FRU(s) within the extract period (See Note 1)
	`<lastExtractedEmpID>?</lastExtractedEmpID>`		`EmpID`	start the extract from the operative after this (for use after error)
	`<requiredObjects>?</requiredObjects>`			list of external data objects required in the return
	`<options>`			currently unused but allows for future extensions to behaviour
		`<unused>?</unused>`
	`</options>`
`</sp:GetChangedEmpRequest>`

Notes:

if both FRU and Team are null select all

The ‘added’ case will return all requested external objects that the operative has defined if the operative has been created since the lastExtractTime, or if an operative who previously had his/her final posting ended has been given () a new posting that means that operative is once again a ‘current’ posting.

‘Update’ records will only be sent if changes have been applied, to either the external data attributes themselves or to the ServiceOptimizer attributes they reference, since the lastExtractTime. For any requested object a change to any of the attributes will mean that all attributes will be returned, however each will have a ‘modified’ Boolean so that the caller knows which have been changed within the extract timeframe.

When an external data object is requested, if an operative has some of the external data attributes for that object defined, but not all of them, then only the attributes where the operative has a defined value will be returned. If an operative has no attributes for a particular object defined then the object is not returned for that operative (but there may be other objects returned if the request specified multiple objects)

For deletion records, these will be sent when an operative’s final posting has an end date added, and that end date now falls inside the time period defined by lastExtractTime.

Return Structure

The API returns a non-standard return structure.

Click here to expand...

Web Service				Type	Description	Req?	Val?
`<sp:GetChangedEmpResponse>`
	`<result>?</result>`
	`<totalRecords>?</totalRecords>`				total number of records
	`<numRecords>?</numRecords>`				number in this response (will be < total if lastExtractedEmpID is used)
	`<Emps>`
		`<empID>?</empID>`		`EmpID`
		`<recordType>?</recordType>`			defines whether the rest of the record defines an added, updated or deleted operative.
		`<externalObject>`
		`<name>?</name>`
		`<externalData>`
			`<name>?</name>`
			`<value>?</value>`
			`<modified>?</modified>`
			`</externalData>`
		`</externalObject>`
	`</Emps>`
`</sp:GetChangedEmpResponse>`

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_EMPID_INVALID (5)
SP_OPTIONS_INVALID (80)
SP_TEAMID_INVALID (200)
SP_EMPID_DOES_NOT_EXIST (231)
SP_TEAMID_DOES_NOT_EXIST (249)
SP_FRUID_INVALID (278)
SP_FRUS_AND_TEAMS_BOTH_SUPPLIED (316)
SP_DATETIME_INVALID (538)
SP_FRUID_DOES_NOT_EXIST (636)
SP_EXTERNAL_NAME_INVALID (659)

ServiceScheduling 13.3

Integration ServiceOptimizer Operative External Data SOAP API

Description

Definition

Return Structure

Return Codes

Description

Definition

Return Structure

Return Codes