Description

The sp:EmpCreateRequest API method allows the creation of new employees, so that the team postings, skills, shift assignments and locations, local knowledge and public holiday assignments are all specified in one call, as well as all the other attributes of an employee. The newly created employee becomes available in the rest of ServiceOptimizer in real time.

It is also possible to create operative related data for externals systems, allowing ServiceManager to become a single point of management for this data.

Definition

The definition of this API is:

Click here to expand...

This API contains the same information (and constraints) as if setting up an operative in ServiceManager. With this in mind, the detailed descriptions of each of the fields is limited in this document.

Web Service					Type	Description	Req?	Val?
`<sp:EmpCreateRequest>`
	`<empID>?</empID>`				`EmpID`
	`<empAttr>`
		`<type>?</type>`				SPET_Employee
		`<name>?</name>`
		`<surname>?</surname>`
		`<jobTitle>?</jobTitle>`
		`<efficiency>?</efficiency>`			`int`	How efficient is the employee? Value is used as a multiplier on the job duration. More efficient engineers will take less time to do the job. Value must be between (inclusive) 10 and 999. Normal value is 100
		`<maxOvertime>?</maxOvertime>`			`int`	What is the maximum amount of planned overtime that can be used for this employee? Values must be between (inclusive) 0 and 999.
		`<informLeadTime>?</informLeadTime>`			`int`	Normally the range of allowed values for InformLeadTime is held in the ServiceOptimizer database (i.e. between (inclusive) sp083.min_value and sp083.max_value where name = “TIL”). If either of these is not in the database, then the supplied value of InformLeadTime must be between 0 and 9999 respectively. If no informLeadTime is set for the employee then the FRU or system level ILT parameter will be used.
		`<earmarkedJobsMax>?</earmarkedJobsMax>`			`int`	The maximum number of jopbs that can be earmarked at any one time for this employee. Mst be between (inclusive) 1 and 99. If no value is set then the system/FRU levels are used.
		`<homePostcode>?</homePostcode>`			`Postcode`
		`<workPostcode>?</workPostcode>`			`Postcode`
		`<TZType>?</TZType>`			`EmpTZType`
		`<workTZ>?</workTZ>`				WorkTZ is a TimeZone of the form ‘Mountain’, ‘Eastern’ ‘Greenwich’. The chosen value must exist in the ServiceOptimizer database.
		`<available>?</available>`			`boolean`	Should the employee be schedulable
		`<defaultStartLoc>`
			`<locType>?</locType>`
			`<postcode>?</postcode>`		`Postcode`
		`</defaultStartLoc>`
		`<defaultEndLoc>`
			`<locType>?</locType>`
			`<postcode>?</postcode>`		`Postcode`
		`</defaultEndLoc>`
		`<defaultLKCLoc>`
			`<locType>?</locType>`
			`<postcode>?</postcode>`		`Postcode`
		`</defaultLKCLoc>`
		`<address1>?</address1>`
		`<address2>?</address2>`
		`<address3>?</address3>`
		`<address4>?</address4>`
		`<phone1>?</phone1>`
		`<phone2>?</phone2>`
		`<pager>?</pager>`
		`<handHeldAdd1>?</handHeldAdd1>`
		`<handHeldAdd2>?</handHeldAdd2>`
		`<currentHandHeld>?</currentHandHeld>`
		`<printer>?</printer>`
		`<vehicleCapacity>?</vehicleCapacity>`
		`<TOTB>?</TOTB>`				must be between (inclusive) 0 and 1440
		`<TOTA>?</TOTA>`				must be between (inclusive) 0 and 1440
		`<showOperativeStatus>?</showOperativeStatus>`
		`<showTravelStatus>?</showTravelStatus>`
		`<freezeTheDayLeadTime>?</freezeTheDayLeadTime>`				both FreezeTheDayLeadTime and FreezeTheDayTimeOfDay should be supplied or both should not be supplied. If only one is supplied, either SP_FDLT_NOT_SUPPLIED (586) or SP_FDT_NOT_SUPPLIED (587) will be returned. In a call of EmpUpdateRequest, both can be supplied or neither can be supplied. Also, only one of them can be supplied as long as the other is already set for this operative.
		`<freezeTheDayTimeOfDay>?</freezeTheDayTimeOfDay>`				SP_TIME_INVALID (29) (29) will be returned if the supplied FreezeTheDayTimeOfDay isn’t between 0000 and 2400.
		`<customKWVs>`				The two Keywords that can be supplied in CustomKWVs are HourlyRate and OvertimeRate
			`<keyword>?</keyword>`
			`<value>?</value>`
		`</customKWVs>`
	`</empAttr>`
	`<postings>`					A posting is an association between an operative and a team (TeamID) which represents the fact that the operative is assigned to that team for a period of time between startDate and endDate. By implication, the operative is also assigned to the FRU containing the IRU containing that team for that time period, and so may be allocated jobs that have been booked into that FRU. Postings can’t overlap in time, but there can be gaps between an operative’s postings when he can’t be assigned any jobs or standard activities.
		`<teamID>?</teamID>`
		`<startDate>?</startDate>`
		`<endDate>?</endDate>`				If the end of a posting isn’t specified, then it’s assumed that the operative is posted to that team ‘for ever’.
	`</postings>`
	`<skills>`					An operative may have any number of skills, each for a particular time period.
		`<skillWithLevel>`
			`<skillID>?</skillID>`		`SkillID`
			`<skillLevel>?</skillLevel>`			Each skill has a level associated with it that represents the level of that skill that the operative possesses. The scheduling process makes sure that that an operative is not assigned a job for which he doesn’t have all of the required skills at the required level or above.
		`</skillWithLevel>`
		`<startDate>?</startDate>`
		`<endDate>?</endDate>`				If the end isn’t specified, then the operative has the skill ‘for ever’.
	`</skills>`
	`<shifts>`					A shift pattern is a repeating sequence of time periods when operatives may have jobs automatically allocated.
		`<shiftPatternID>?</shiftPatternID>`
		`<startDate>?</startDate>`				A shift pattern assignment is a period of days (between startDate and endDate) when an operative is ‘working’ a particular shift pattern.
		`<endDate>?</endDate>`				If endDate isn’t specified, then it’s assumed that the operative will work that shift pattern ‘for ever’.
	`</shifts>`
	`<defaultRangeLKs>`
		`<travelTime>?</travelTime>`				TravelTime must be less than 255
		`<LKValue>?</LKValue>`				All supplied values of LKValue must be between 0 & 10
	`</defaultRangeLKs>`
	`<defaultRegionLKs>`
		`<regionID>?</regionID>`
		`<LKValue>?</LKValue>`				the LKValue must be between 0 & 10
	`</defaultRegionLKs>`
	`<pubHols>?</pubHols>`
	`<workPatt>`					This allowsLocalKnowledgeRanges, Local Knowledge Regions, Local Knowledge Centres, Start Locations and End Locations to be supplied as part of a multi-week repeating work pattern.
		`<syncDate>?</syncDate>`				The syncDate parameter is a date on which the corresponding day of the week of the first week of a multi-week Working Pattern should coincide (not the date on which the Working Pattern starts). For example if the Working Pattern is for 4 weeks starting on a Monday, and the SyncDate is 16^th March 2005 ( a Wednesday), the first Wednesday of the Working Pattern should be on 16^th march 2005. The second Wednesday will therefore be on 23^rd March 2005. The previous Sunday (13^th March 2005) will be for the fourth Sunday in the four week Working Pattern since it starts on a Monday.
		`<workPattDay>`
			`<weekNum>?</weekNum>`
			`<day>?</day>`		`DayOfTheWeek`
			`<rangeLKoption>?</rangeLKoption>`
			`<rangeLK>`
				`<travelTime>?</travelTime>`
				`<LKValue>?</LKValue>`
			`</rangeLK>`
			`<regionLKoption>?</regionLKoption>`
			`<regionLK>`
				`<regionID>?</regionID>`
				`<LKValue>?</LKValue>`
			`</regionLK>`
			`<startLoc>`
				`<locType>?</locType>`
				`<postcode>?</postcode>`	`Postcode`
			`</startLoc>`
			`<endLoc>`
				`<locType>?</locType>`
				`<postcode>?</postcode>`	`Postcode`
			`</endLoc>`
			`<LKCLoc>`
				`<locType>?</locType>`
				`<postcode>?</postcode>`	`Postcode`
			`</LKCLoc>`
		`</workPattDay>`
	`</workPatt>`
	`<options>`
		`<AllowShiftsTooClose>?</AllowShiftsTooClose>`				AllowShiftsTooClose overrides the limit on how close shift patterns are allowed to be
	`</options>`
	`<externalData>`					See 15.6
		`<name>?</name>`
		`<SPESDTType>?</ SPESDTType >`
		`<value>?</value>`
	`</externalData>`
`</sp:EmpCreateRequest>`

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_EMPID_INVALID (5)
SP_SKILLLEVEL_INVALID (32)
SP_EMPID_ALREADY_EXISTS (42)
SP_NAME_NOT_SUPPLIED (46)
SP_MANDATORY_SURNAME_NULL (48)
SP_OUTSIDE_HORIZON (53)
SP_EMPNAME_INVALID (133)
SP_EMPSURNAME_INVALID (134)
SP_EMPJOBTITLE_INVALID (135)
SP_EMPADDRESS1_INVALID (136)
SP_EMPADDRESS2_INVALID (137)
SP_EMPADDRESS3_INVALID (138)
SP_EMPADDRESS4_INVALID (139)
SP_EMPPHONE1_INVALID (140)
SP_EMPPHONE2_INVALID (141)
SP_PAGERNO_INVALID (142)
SP_EMPTYPE_INVALID (184)
SP_EFFICIENCY_INVALID (185)
SP_MAXOVERTIME_INVALID (186)
SP_ILT_INVALID (187)
SP_EARMARKEDJOBSMAX_INVALID (188)
SP_HOMEPOSTCODE_INVALID (189)
SP_WORKPOSTCODE_INVALID (190)
SP_EMPTZTYPE_INVALID (191)
SP_WORKTZ_INVALID (192)
SP_AVAILABLE_INVALID (193)
SP_HANDHELDADD1_INVALID (194)
SP_HANDHELDADD2_INVALID (195)
SP_CURRENTHANDHELD_INVALID (196)
SP_PRINTER_INVALID (197)
SP_TEAMID_INVALID (200)
SP_POSTINGSTARTDATE_INVALID (201)
SP_POSTINGENDDATE_INVALID (202)
SP_POSTINGTYPE_INVALID (203)
SP_SKILLSTARTDATE_INVALID (204)
SP_SKILLENDDATE_INVALID (205)
SP_SHIFTPERIODTYPE_INVALID (206)
SP_SKILLISDERIVED_INVALID (207)
SP_SHIFTPATTERNID_INVALID (208)
SP_SHIFTASSSTARTDATE_INVALID (209)
SP_SHIFTASSENDDATE_INVALID (210)
SP_EMPCREATEOPTIONS_INVALID (211)
SP_SKILLID_NOT_SUPPLIED (213)
SP_EMPID_NOT_SUPPLIED (215)
SP_HOMEPOSTCODE_NOT_SUPPLIED (220)
SP_WORKTZ_NOT_SUPPLIED (221)
SP_TEAMID_NOT_SUPPLIED (222)
SP_POSTINGSTARTDATE_NOT_SUPPLIED (223)
SP_SKILLSTARTDATE_NOT_SUPPLIED (226)
SP_SHIFTPATTERNID_NOT_SUPPLIED (227)
SP_SHIFTASSSTARTDATE_NOT_SUPPLIED (228)
SP_HOMEPOSTCODE_DOES_NOT_EXIST (232)
SP_WORKPOSTCODE_DOES_NOT_EXIST (233)
SP_WORKTZ_DOES_NOT_EXIST (234)
SP_POSTING_START_GE_END (238)
SP_SKILL_START_GE_END (239)
SP_SHIFTASS_START_GE_END (240)
SP_POSTINGS_OVERLAP (241)
SP_SHIFTASS_OVERLAP (242)
SP_SKILLS_OVERLAP (243)
SP_HOMEPOSTCODE_NOT_MAPPED (244)
SP_WORKPOSTCODE_NOT_MAPPED (245)
SP_TEAMID_DOES_NOT_EXIST (249)
SP_SKILLID_DOES_NOT_EXIST (250)
SP_SHIFTPATTERNID_DOES_NOT_EXIST (251)
SP_SKILLID_INVALID (253)
SP_REGIONID_INVALID (277)
SP_STARTLOC_INVALID (304)
SP_STARTLOCPOSTCODE_INVALID (305)
SP_ENDLOC_INVALID (306)
SP_ENDLOCPOSTCODE_INVALID (307)
SP_STARTLOCPOSTCODE_DOES_NOT_EXIST (309)
SP_ENDLOCPOSTCODE_DOES_NOT_EXIST (310)
SP_STARTLOCPOSTCODE_NOT_SUPPLIED (314)
SP_ENDLOCPOSTCODE_NOT_SUPPLIED (315)
SP_PUBHOLSETID_INVALID (330)
SP_PUBHOLSETID_DOES_NOT_EXIST (331)
SP_RANGELKS_TRAVEL_INVALID (341)
SP_RANGELKS_LKVALUE_INVALID (342)
SP_RANGELKS_DUPLICATE (343)
SP_SHIFTS_WOULD_OVERLAP (344)
SP_SHIFTS_TOO_CLOSE (345)
SP_LKCLOC_INVALID (347)
SP_LKCLOCPOSTCODE_DOES_NOT_EXIST (348)
SP_LKCLOCPOSTCODE_NOT_SUPPLIED (349)
SP_LKCLOCPOSTCODE_INVALID (350)
SP_DST_TIME_INVALID (379)
SP_VEHICLE_CAPACITY_INVALID (393)
SP_DOTW_INVALID (394)
SP_TOTB_INVALID (409)
SP_CUSTOMKWVSEQ_SIZE_INVALID (425)
SP_CUSTOMKEYWORD_INVALID (426)
SP_CUSTOMVALUE_INVALID (427)
SP_CUSTOMKEYWORD_DOES_NOT_EXIST (428)
SP_TOTA_INVALID (445)
SP_PUBHOLSETID_DUPLICATED (452)
SP_CUSTOMKWVSEQ_CUSTOMKWVS_NULL (454)
SP_PUBHOLSETSEQ_PUBHOLSETS_NULL (455)
SP_REGIONLKS_LKVALUE_DOES_NOT_EXIST (456)
SP_LKRANGE_LKVALUE_DOES_NOT_EXIST (458)
SP_TRAVELTIME_INVALID (459)
SP_REQ_OPTION_NOT_SET (471)
SP_EMPWORKPATT_DAYS_NULL (472)
SP_LOCKNOWREGIONSEQ_REGIONS_NULL (473)
SP_LOCKNOWRANGESEQ_RANGES_NULL (474)
SP_EMPWORKPATT_SIZE_GT_MAX (478)
SP_WPD_DUPLICATED (479)
SP_EMP_WPD_WEEKNUM_INVALID (480)
SP_DEFAULT_RANGE_DUPLICATED (481)
SP_DEFAULT_REGION_DUPLICATED (482)
SP_EMP_WPD_RANGE_DUPLICATED (483)
SP_EMP_WPD_REGION_DUPLICATED (484)
SP_REGIONLKS_LKVALUE_INVALID (488)
SP_EMPWORKPATT_SYNC_DATE_INVALID (489)
SP_CUSTOMKEYWORD_DUPLICATED (451)
SP_SHOWOPERATIVESTATUS_INVALID (570)
SP_SHOWTRAVELSTATUS_INVALID (571)
SP_FDLT_NOT_SUPPLIED (586)
SP_FDT_NOT_SUPPLIED (587)
SP_NO_WORKPOSTCODE_FOR_DEFAULTSTARTLOC (589)
SP_NO_WORKPOSTCODE_FOR_DEFAULTENDLOC (590)
SP_NO_WORKPOSTCODE_FOR_DEFAULTLKCLOC (591)
SP_NO_WORKPOSTCODE_FOR_WORKPATT_STARTLOC (592)
SP_NO_WORKPOSTCODE_FOR_WORKPATT_ENDLOC (593)
SP_NO_WORKPOSTCODE_FOR_WORKPATT_LKCLOC (594)
SP_NO_DEPOT_FOR_DEFAULTSTARTLOC (595)
SP_NO_DEPOT_FOR_DEFAULTENDLOC (596)
SP_NO_DEPOT_FOR_DEFAULTLKCLOC (597)
SP_NO_DEPOT_FOR_WORKPATT_STARTLOC (598)
SP_NO_DEPOT_FOR_WORKPATT_ENDLOC (599)
SP_NO_DEPOT_FOR_WORKPATT_LKCLOC (600)
SP_DUPLICATE_EXTERNAL_NAME (661)
SP_OK_CAPACITY_EXCEEDED (640)
SP_TEAM_CHANGE_REQUIRES_RESTART (647)
SP_EXTERNAL_NAME_INVALID (659)
SP_EXTERNAL_SPESDTTYPE_INVALID (660)
SP_EXTERNAL_VALUE_INVALID (663)

Browser not supported