Pass Through Call to ServiceScheduling's "EmpAddActRequest" APIThis RESTified API will perform a pass-through call to the ServiceScheduling sub-system's "EmpAddActRequest" API (when configured). URL| Panel |
|---|
| borderColor | grey |
|---|
| bgColor | whitesmoke |
|---|
| borderStyle | solid |
|---|
| PUT /up/v5/rest/scheduling/EmpAddAct
|
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 "EmpAddActRequest" API. | Code Block |
|---|
| language | js |
|---|
| title | EmpAddAct JSON |
|---|
| collapse | true |
|---|
| {
"empID": "",
"actType": "",
"expectedStart": "",
"expectedEnd": "",
"locType": "",
"notes": "",
"TZType": "",
"Dispatch": false,
"TravelMode": "",
"Duration": "",
"Options": {
"CheckJobs": false,
"CheckStdActs": false,
"CheckJobsDealloc": false,
"CheckJobsShuffle": false,
"CheckJobsAllowBreakAH": false,
"CheckFrozen": false,
"OverlapBreaks": false
}
} |
EmpAddAct Object Properties| Property | Type | Length | Description | Req? | Field Mapping: ServiceScheduling |
|---|
| empID | string
| SS: |
EmpID (string)SS: 25 | Identifier of the employee that the newly created standard activity will be allocated to.
| Yes |
SS Field Mapping:YesstringSS: ActTypeStr ()Yes | SS: 30 | Type of standard activity which should be created |
SS Field Mapping: actType Yes | ActTypeStr | expectedStart | string | SS: |
spDate (string)SS: 8 | Date and time of when the new standard activity should start (employee local or default – see 12). If the time part isn’t supplied, it defaults to the start of the operative’s day. Local to the employee doing the activity or, if the employee has no timezone, local to the default timezone. Example: "2023-03-30" | Yes |
SS Field Mapping:YesstringSS: spDate () | SS: 8 | Date and time (employee local or default) when the new standard activity should end. If the time part isn’t supplied, it defaults to the end of the operative’s day. If an empty string (“”) is supplied, the new activity will last indefinitely but this is only allowed if the employee is posted to the same FRU (but not necessarily to the same Team within that FRU) indefinitely, otherwise SP_POSTING_HAS_ENDDATE (285) will be returned. expectedEnd and expectedDuration cannot both be populated – if both are then SP_SA_CONFLICTING_END (665) will be returned. Local to the employee doing the activity or, if the employee has no timezone, local to the default timezone. Example: "2023-03-30" | No |
SS Field Mapping:NoEmpLocType (string)SS: See Valid Values | Specifies where the new standard activity is to be located: at a supplied postal code (in Act.EndPostCode (below)), at the employee’s home region, at the employee’s depot’s region (not available in V4.4 if the operative isn’t on shift), at the employee’s work region, at the employee’s start region on the day of the activity (if he’s on shift), taking overrides into account, at the employee’s end region on the day of the activity (if he’s on shift), taking overrides into account Note: Can be missing but, unless StandardActivityTravelMode has a value other than NoTravel, this will result in SP_ACT_LOC_TYPE_INVALID (152) being returned, since the activity’s location must be known to SERVICEOptimizer for travel to be included. SS |
Field Mapping: locTypeSS No Valid Values: "Home", "Work", "Depot", "Supplied", "None" | No | locType | | notes | String | SS: 503 | This field is for user annotation and can either be any text string or it can be empty (“”). It appears on the Gantt Show Activity Details window, where it can also be edited. |
SS Field Mapping: notes ActTZType | SS: See Valid Values | Defaults to Employee Time Zone. |
SS Field Mapping: TZTypeNoSS Valid Values: "Home", "FRU", "Location", "Default" | No | ActTZType | | Dispatch | Boolean |
| Determines whether or not this specific standard activity will be included in any dispatching process. Defaults to value associated with actType. |
SS Field Mapping: Dispatch No | Dispatch | | TravelMode | String |
SS: ActTravelMode
| SS: See Valid Values | Determines whether the standard activity will be allocated travel and, if so, how that travel behaves w.r.t the start of the SA SS |
Field Mapping: TravelModeSS Valid Values: "None", "ETS", "ETA" | Yes | TravelMode | | Duration |
StringSS: integer |
| The number of minutes the standard activity is expected to last. expectedEnd and expectedDuration cannot both be populated – if both are then SP_SA_CONFLICTING_END (665) will be returned. | No |
SS Field Mapping:No | No| Property | Type | Description | Req? |
|---|
| CheckJobs | Boolean | SP_OVERLAPPED_JOBS (132) will be returned if the new activity would overlap existing jobs. The new activity is not created. | No | | CheckStdActs | Boolean | SP_OVERLAPPED_STDACTS (160) will be returned if the new activity would overlap existing standard activities. The new activity is not created. | No | | CheckJobsDealloc | Boolean | If the new standard activity would overlap existing jobs, those jobs are de-allocated (to the in-tray), unless their status is SPDS_LoggedOff or SPDS_Cleared, in which case they will be left overlapping. The new activity is created. If none of these options is set the new activity is created anyway and any consequent overlaps are left as they are. | No | | CheckJobsShuffle | Boolean | Existing Tentative, Earmarked and Contacted jobs will be shuffled to try to remove overlaps. If removing the overlaps would mean the jobs’ access hours would be broken, then the call is aborted and SP_WOULD_BREAK_ACCESS_HOURS (371) is returned. | No | | CheckJobsAllowBreakAH | Boolean | If this is also set with the above option, the shuffled jobs’ access hours can be broken to remove overlaps. | No | | CheckFrozen | Boolean | SP_FROZEN_DAY (585) is returned if the new activity would be on a date where the engineer’s schedule is frozen. | No | OverlapBreaks | Boolean | Currently not used. This option has been added for future use in determining the behaviour when breaks are overlapped by standard activities. | HTTP ResponseSuccessOn success, a JSON-formatted version of the ServiceScheduling "EmpAddActRequest" API response will be returned. | Code Block |
|---|
| {
"Success": true,
"Code": 0,
"Message": "OK",
"Payload": {
"result": {
"type": "OK",
"code": "0"
},
"actID": "88139"
}
} |
Error On error, a JSON-formatted version of the ServiceScheduling "EmpAddActRequest" 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, the possible Return Codes from this API are: | Expand |
|---|
SP_POSTCODE_INVALID (3)SP_EMPID_INVALID (5)SP_DURATION_INVALID (12)SP_END_NOT_GT_START_TIME (31)SP_OUTSIDE_HORIZON (53)SP_START_TIME_INVALID (62)SP_END_TIME_INVALID (63)SP_OPTIONS_INVALID (80)SP_NO_REG_TO_RU_MAPPING (115)SP_ACTIVITY_TYPE_INVALID (120)SP_ACTIVITY_NOTES_INVALID (123)SP_EMP_NOT_IN_TEAM (124)SP_TEAM_NOT_IN_RU (125)SP_OVERLAPPED_JOBS (132)SP_ACT_LOC_TYPE_INVALID (152)SP_OPTION_COMBINATION_INVALID (159)SP_OVERLAPPED_STDACTS (160)SP_EMPID_DOES_NOT_EXIST (231)SP_POSTING_HAS_ENDDATE (285)SP_SPANS_POSTINGS (286)SP_WOULD_BREAK_ACCESS_HOURS (371)SP_OK_WITH_OVERLAPS (373)SP_DST_TIME_INVALID (379)SP_FROZEN_DAY (585)SP_OK_CAPACITY_EXCEEDED (640)SP_SA_CONFLICTING_END (665)SP_SATM_INVALID (667)SP_SA_DISPATCH_INVALID (670)SP_SA_TRAVELMODE_ENDTIME_INVALID (672)SP_SA_LOCATIONTYPE_MISSING_POSTCODE (673)
|
|
