Pass Through Call to ServiceSchedulingScheduling's "EmpUpdateRequest" APIThis RESTified API will perform a pass-through call to the ServiceScheduling Scheduling sub-system's "EmpUpdateRequest" API (when configured). URL| Panel |
|---|
| borderColor | grey |
|---|
| bgColor | whitesmoke |
|---|
| borderStyle | solid |
|---|
| PUT /up/v5/rest/scheduling/EmpUpdate
|
HTTP Request BodyThis request requires a JSON object supplied in the HTTP request body, which defines the parameters that will be passed through to the ServiceScheduling Scheduling "EmpUpdateRequest" API. | Code Block |
|---|
| language | js |
|---|
| title | EmpUpdate |
|---|
| collapse | true |
|---|
| {
"empID": "",
"empAttr": {
"type": "",
"name": "",
"surname": "",
"jobTitle": "",
"efficiency": "",
"homePostcode": "",
"maxOvertime": "",
"workPostcode": "",
"TZType": "",
"workTZ": "",
"available": false,
"defaultStartLoc": {
"locType": "",
"postcode": ""
},
"defaultEndLoc": {
"locType": "",
"postcode": ""
},
"defaultLKCLoc": {
"locType": "",
"postcode": ""
},
"showOperativeStatus": false,
"showTravelStatus": false,
"address1": "",
"address2": "",
"address3": "",
"address4": "",
"phone1": "",
"phone2": "",
"pager": "",
"handHeldAdd1": "",
"handHeldAdd2": "",
"currentHandHeld": "",
"printer": "",
"vehicleCapacity": "",
"TOTA": "",
"TOTB": "",
"freezeTheDayLeadTime": "",
"freezeTheDayTimeOfDay": "",
"customKWVs": {
"keyword": "",
"value": ""
}
},
"postings": {
"teamID": "",
"startDate": "",
"endDate": ""
},
"skills": [{
"skillWithLevel": {
"skillID": "",
"skillLevel": ""
},
"startDate": "",
"endDate": ""
}],
"shifts": {
"shiftPatternID": "",
"startDate": "",
"endDate": "",
"defaultRangeLKs": {
"travelTime": "",
"LKValue": ""
},
"defaultRegionLKs": {
"regionID": "",
"LKValue": ""
},
"pubHols": "",
"workPatt": {
"syncDate": "",
"workPattDay": {
"weekNum": "",
"day": "",
"rangeLKoption": "",
"rangeLK": {
"travelTime": "",
"LKValue": ""
},
"regionLKoption": "",
"regionLK": {
"regionID": "",
"LKValue": ""
},
"startLoc": {
"locType": "",
"postcode": ""
},
"endLoc": {
"locType": "",
"postcode": ""
},
"LKCLoc": {
"locType": "",
"postcode": ""
}
}
}
},
"options": {
"AllowShiftsTooClose": "",
"AllowAdd": "",
"PostingDeallocJobs": "",
"ShiftAssDeallocJobs": "",
"PostingSet": "",
"SkillSet": "",
"ShiftAssSet": "",
"RangeLKSet": "",
"RangeLKSet": "",
"PubHolSet": "",
"PattSet": "",
"PattRangeLKSet": "",
"PattRegionLKSet": ""
},
"externalData": {
"name": "",
"SPESDTType": "",
"value": ""
}
} |
EmpUpdate Object Properties| Property | Type | Length | Description | Req? |
|---|
| empID | string
SS : EmpID (string) |
SS: 50 | Identifier of the employee that the newly created standard activity will be allocated to. SS Field: empID | Yes | | empAttr | object | N/A | f any of the operative’s attributes are not to be updated, then the relevant field in the supplied EmpAttr should be excluded. Each of the items will normally be updated only if they already exist for this employee. For this purpose, each item is identified by its primary key, i.e: StartDate for Postings, SkillID & StartDate for Skills, StartDate for Shifts (Note: The primary key also includes the EmpID, but this is always supplied in another parameter) If an item in one of the Postings, Skills or Shift Assignments supplied does not already exist (as identified by its primary key), the call will fail. However, if the supplied Options field contains UpdateAllowAdd, then any supplied items that don’t already exist will be created and added to the relevant list. If UpdateAllowAdd isn’t set and one of the supplied items doesn’t exist, then SP_POSTING_DOES_NOT_EXIST (235), SP_SKILLASS_DOES_NOT_EXIST (237) or SP_SHIFTASS_DOES_NOT_EXIST (236) will be returned, as appropriate.
| Property | Type | Length | Description |
|---|
| type | string | SS: See Valid Values | Employee Type SS Field: empAttr.type SS Valid Values: "Employee", "Crew", "ContractCrew", "MAXPLUS1" | | name | string | SS: 50 | Operative's first name SS Field: empAttr.name | | surname | string | SS: 50 | Operative's last name SS Field: empAttr.surname | | jobTitle | string | SS: 24 | Operative's job title SS Field: empAttr.jobTitle | | efficiency | integer |
| 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 SS Field: empAttr.efficiency | | homePostcode | string SS: Postcode (string) | SS: 30 SM: 10 | Home post code SS Field: empAttr.homePostcode | | workPostcode | string SS: OptPostcode | SS: 30 SM: 10 | Work post code SS Field: empAttr.workPostcode | | maxOvertime | unsigned integer |
| What is the maximum amount of planned overtime that can be used for this employee? Values must be between (inclusive) 0 and 999. SS Field: empAttr.maxOvertime | | informLeadTime | unsigned int |
| SS Field: empAttr.informLeadTime | | earmarkedJobsMax | unsigned int |
| SS Field: empAttr.earmarkedJobsMax | | TZType | string SS: EmpTZType (string) | SS: See Valid Values | SS Field: empAttr.TZType SS Valid Values: "None", "Supplied", "Home", "Depot", "RU", "MAXPLUS1" | | workTZ | string SS: EmpTZType (string) | SS: See Valid Values | SS Field: empAttr.workTZ SS Valid Values: "None", "Supplied", "Home", "Depot", "RU", "MAXPLUS1" | | available | boolean |
| SS Field: empAttr.available | | defaultStartLoc | object |
|
| Property | Type | Length | Description |
|---|
| locType | string SS: EmpLocType (string) | SS: See Valid Values | SS Field: empAttr.defaultStartLoc.locType SS Valid Values: "Home", "Work", "Depot", "Supplied", "None" | | postCode | string SS: OptPostcode (string) | SS: 30 SM: 10 | SS Field: empAttr.defaultStartLoc.postCode |
| | defaultEndLoc | object |
|
| Property | Type | Length | Description |
|---|
| locType | string SS: EmpLocType (string) | SS: See Valid Values | SS Field: empAttr.defaultEndLoc.locType SS Valid Values: "Home", "Work", "Depot", "Supplied", "None" | | postCode | string SS: OptPostcode (string) | SS: 30 SM: 10 | SS Field: empAttr.defaultEndLoc.postCode |
| | defaultLKCLoc | object |
|
| Property | Type | Length | Description |
|---|
| locType | string SS: EmpLocType (string) | SS: See Valid Values | SS Field: empAttr.defaultLKCLoc.locType SS Valid Values: "Home", "Work", "Depot", "Supplied", "None" | | postCode | string SS: OptPostcode (string) | SS: 30 SM: 10 | SS Field: empAttr.defaultKCLoc.postCode |
| | showOperativeStatus | boolean |
| SS Field: empAttr.showOperativeStatus | | showTravelStatus | boolean |
| SS Field: empAttr.showTravelStatus | | address1 | string SS: EmpAddress (string) | SS: 50 | SS Field: empAttr.address1 | | address2 | string SS: EmpAddress (string) | SS: 50 | SS Field: empAttr.address2 | | address3 | string SS: EmpAddress (string) | SS: 50 | SS Field: empAttr.address3 | | address4 | string SS: EmpAddress (string) | SS: 50 | SS Field: empAttr.address4 | | phone1 | string SS: PhoneNum (string) | SS: 40 | SS Field: empAttr.phone1 | | phone2 | string SS: PhoneNum (string) | SS: 40 | SS Field: empAttr.phone2 | | pager | string SS: PagerNum (string) | SS: 20 | SS Field: empAttr.pager | | handHeldAdd1 | string SS: HandHeldAddress (string) | SS: 10 | SS Field: empAttr.handHeldAdd1 | | handHeldAdd2 | string SS: HandHeldAddress (string) | SS: 10 | SS Field: empAttr.handHeldAdd2 | | currentHandHeld | string SS: CurrentHandHeldNum (unsigned integer) |
| SS Field: empAttr.currentHandHeld | | printer | string SS: EmpPrinterName | SS: 10 | SS Field: empAttr.printer | | vehicleCapacity | unsigned integer |
| SS Field: empAttr.vehicleCapacity | | TOTA | integer |
| must be between (inclusive) 0 and 1440 SS Field: empAttr.TOTA | | TOTB | integer |
| must be between (inclusive) 0 and 1440 SS Field: empAttr.TOTB | | freezeTheDayLeadTime | string SS: FreezeTheDayLeadTime (unsigned integer) |
| 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. SS Field: empAttr.freezeTheDayLeadTime | | freezeTheDayTimeOfDay | string SS: spTime (string) | SS: 15 | SP_TIME_INVALID (29) (29) will be returned if the supplied FreezeTheDayTimeOfDay isn’t between 0000 and 2400. Example: "14:15" SS Field: empAttr.freezeTheDayTimeOfDay | | customKWVs | object | 2 | The two Keywords that can be supplied in CustomKWVs are HourlyRate and OvertimeRate
| Property | Type | Length | Description |
|---|
| keyword | string SS: CustomKeyword | SS: min 1, max 10 | SS Field: empAttr.customKWVs.keyword | | value | string SS: CustomValue | SS: min 1, max 20 | SS Field: empAttr.customKWVs.value |
|
|
| | postings | object | N/A | 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.
| Property | Type | Length | Description |
|---|
| teamID | string SS: TeamID (string) | SS: 40 | SS Field: postings.teamID | | startDate | string SS: spDate (string) | SS: 8 | Example: "2023-03-30" SS Field: postings.startDate | | endDate | string SS: spDate (string) | SS: 8 | If the end of a posting isn’t specified, then it’s assumed that the operative is posted to that team ‘forever’. Example: "2023-03-30" SS Field: postings.endDate |
|
| | skills | array |
| An operative may have any number of skills, each for a particular time period.
| Property | Type | Length | Description |
|---|
| skillWithLevel | object |
|
| Property | Type | Length | Description |
|---|
| skillID | SS: SkillID | SS: 30 | SS Field: skills.skillWithLevel.skillID | | skillLevel | SS: SkillLevel (unsigned integer) |
| 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. SS Field: skills.skillWithLevel.skillLevel |
| | startDate | string SS: spDate (string) | SS: 8 | Example: "2023-03-30" SS Field: skills.startDate | | endDate | string SS: spDate (string) | SS: 8 | Example: "2023-03-30" SS Field: skills.endDate |
| | | shifts | object | N/A |
| Property | Type | Length | Description |
|---|
| shiftPatternID | string SS: ShiftPatternID (string) | SS: 30 | SS Field: shifts.shiftPatternID | | startDate | string SS: spDate (string) | SS: 8 | A shift pattern assignment is a period of days (between startDate and endDate) when an operative is ‘working’ a particular shift pattern. Example: "2023-03-30" SS Field: shifts.startDate | | endDate | SS: spDate (string) | SS: 8 | If endDate isn’t specified, then it’s assumed that the operative will work that shift pattern ‘forever’. Example: "2023-03-30" SS Field: shifts.endDate |
|
| | defaultRangeLKs | object |
|
| Property | Type | Length | Description |
|---|
| travelTime | SS: TravelTime (unsigned int) | SS: min 0, max 255 | TravelTime must be less than 255 SS Field: shifts.defaultRangeLKs.travelTime | | LKValue | SS: LKValue (unsigned int) | SS: min 0, max 10 | All supplied values of LKValue must be between 0 & 10 SS Field: shifts.defaultRangeLKs.LKValue |
|
| | defaultRegionLKs | object |
|
| Property | Type | Length | Description |
|---|
| regionID | string SS: RegionID (string) | SS: 26 | SS Field: shifts.defaultRegionLKs.regionID | | LKValue | SS: LKValue (unsigned int) | SS: min 0, max 10 | the LKValue must be between 0 & 10 SS Field: shifts.defaultRegionLKs.LKValue |
|
| | pubHols | string | SS: 30 | SS Field: shifts.pubHols | | | workPatt | object |
| 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. | Property | Type | Length | Description |
|---|
| syncDate | string SS: spDate (string) | SS: 8 | 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 16th March 2005 ( a Wednesday), the first Wednesday of the Working Pattern should be on 16th march 2005. The second Wednesday will therefore be on 23rd March 2005. The previous Sunday (13th March 2005) will be for the fourth Sunday in the four week Working Pattern since it starts on a Monday. SS Field: shifts.workPatt.syncDate | | workPattDay | object |
|
| Property | Type | Length | Description |
|---|
| weekNum | unsigned int |
| SS Field: shifts.workPattDay.weekNum | | day | DayOfTheWeek | | SS Field: shifts.workPattDay.DayOfTheWeek | | rangeLKoption | WorkPattDay-regionLKoption |
| SS Field: shifts.workPattDay.rangeLKoption | | rangeLK | object EmpLocKnowRegion |
|
| Property | Type | Length | Description |
|---|
| travelTime |
|
| SS Field: shifts.workPattDay.rangeLK.travelTime | | LKValue |
|
| SS Field: shifts.workPattDay.rangeLK.LKValue |
| | regionLKoption | string SS: WorkPattDay-regionLKoption | SS: See Valid Values | SS Field: shifts.workPattDay.regionLKoption SS Valid Values: "empDefaultRegionLK", "noRegionLK" | | regionLK | object |
|
| Property | Type | Length | Description |
|---|
| regionID | string SS: RegionID (string) | SS: 26 | SS Field: shifts.workPattDay.regionLK.regionID | | LKValue | SS: LKValue (unsigned int) | SS: min 0, max 10 | SS Field: shifts.workPattDay.regionLK.LKValue |
| | startLoc | object |
|
| Property | Type | Length | Description |
|---|
| locType | string SS: EmpLocType | SS: See Valid Values | SS Field: shifts.workPattDay.startLoc.locType SS Valid Values: "Vehicle" | | postcode | Postcode | SS: 30 SM: 10 | SS Field: shifts.workPattDay.startLoc.postcode |
| | endLoc | object |
|
| Property | Type | Length | Description |
|---|
| locType | string SS: EmpLocType | SS: See Valid Values | SS Field: shifts.workPattDay.endLoc.locType SS Valid Values: "Vehicle" | | postcode | Postcode | SS: 30 SM: 10 | SS Field: shifts.workPattDay.endLoc.postcode |
| | LKCLoc | object |
|
| Property | Type | Length | Description |
|---|
| locType | string SS: EmpLocType | SS: See Valid Values | SS Field: shifts.workPattDay.LKCLoc.locType SS: See Valid Values | | postcode | Postcode | SS: 30 SM: 10 | SS Field: shifts.workPattDay.LKCLoc.postcode |
|
|
| | | options | object | N/A |
| Property | Type | Description |
|---|
| AllowShiftsTooClose | boolean | AllowShiftsTooClose overrides the limit on how close shift patterns are allowed to be SS Field: options.AllowShiftsTooClose |
|
| | externalData | object | N/A |
| Property | Type | Length | Description |
|---|
| name | string |
| SS Field: externalData.name | | SPESDTType | string SS: SPESDTType | SS: See Valid Values | SS Field: externalData.SPESDTType SS Valid Values: "Specified", "EmpID", "Name", "Surname", "HomePostcode", "WorkPostcode", "AddressLine1"," AddressLine2", "AddressLine3", "AddressLine4","Phone1", "Phone2", "Pager", "WorkTZ", "Team", "FRU", "Depot" | | value | string |
| SS Field: externalData.value |
|
|
HTTP ResponseSuccessOn success, a JSON-formatted version of the ServiceScheduling Scheduling "EmpUpdateRequest" API response will be returned. | Code Block |
|---|
| {
"Success": true,
"Code": 0,
"Message": "OK",
"Payload": {
"result": {
"type": "OK",
"code": "0"
}
}
} |
Error On error, a JSON-formatted version of the ServiceScheduling Scheduling "EmpUpdateRequest" API response will be returned. | Code Block |
|---|
| {
"Success": false,
"Code": 9,
"Payload": {
"returnCode": {
"type": "Error",
"code": "SCH Error Code"
}
}
} |
Return CodesIn addition to the Standard Return Codes, and the ServiceScheduling API return Scheduling Error codes, the possible Return Codes from this API are:
|
