Pass Through Call to ServiceScheduling's "EmpCreateRequest" APIThis RESTified API will perform a pass-through call to the ServiceScheduling sub-system's "EmpCreateRequest" API (when configured). URL Panel |
---|
borderColor | grey |
---|
bgColor | whitesmoke |
---|
borderStyle | solid |
---|
| PUT /up/v5/rest/scheduling/EmpCreate
|
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 "EmpCreateRequest" API. Code Block |
---|
language | js |
---|
title | EmpCreate |
---|
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": ""
},
"externalData": {
"name": "",
"SPESDTType": "",
"value": ""
}
} |
EmpAddAct Object PropertiesProperty | 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 | Property | Type | Length | Description | Req? |
---|
type | string | SS: See Valid Values | Employee Type SS Field: empAttr.type SS Valid Values: "Employee", "Crew", "ContractCrew", "MAXPLUS1" |
| name | string | SS: 50 | Operative first name SS Field: empAttr.name |
| surname | string | SS: 50 | Operative last name SS Field: empAttr.surname |
| jobTitle | string | SS: 24 | Operative 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 | Yes | 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 | Yes | informLeadTime | unsigned 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. SS Field: empAttr.informLeadTime | | earmarkedJobsMax | unsigned int |
| The maximum number of jobs that can be earmarked at any one time for this employee. Must be between (inclusive) 1 and 99. If no value is set then the system/FRU levels are used. SS Field: empAttr.earmarkedJobsMax | | TZType | string SS: EmpTZType (string) | SS: See Valid Values | Time Zone Type SS Field: empAttr.TZType SS Valid Values: "None", "Supplied", "Home", "Depot", "RU", "MAXPLUS1" | | workTZ | string SS: EmpTZType (string) | SS: See Valid Values | WorkTZ is a TimeZone of the form ‘Mountain’, ‘Eastern’ ‘Greenwich’. The chosen value must exist in the ServiceOptimizer database. SS Field: empAttr.workTZ SS Valid Values: "None", "Supplied", "Home", "Depot", "RU", "MAXPLUS1" | | available | Boolean |
| Should the employee be schedulable. SS Field: empAttr.available | | defaultStartLoc | object |
| Default starting location for an operative for a day. Property | Type | Length | Description |
---|
locType | string SS: EmpLocType (string) | SS: | 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 |
| Default end location for an operative for a day. 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 |
| Default Local Knowledge Centre for an operative for a day 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. Example: "2023-03-30" 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 "EmpCreateRequest" 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 "EmpCreateRequest" API response will be returned. Code Block |
---|
| {
"Success": false,
"Code": 9,
"Payload": {
"returnCode": {
"type": "Error",
"code": "SCH Error Code"
}
}
} |
Return CodesIn addition to to the Standard Return Codes, and the ServiceScheduling Error codes, the possible Return Codes from this API are: |