Bulk update resource work schedules

post

/rest/ofscCore/v1/resources/custom-actions/bulkUpdateWorkSchedules

This operation creates, updates, or deletes work schedules of multiple resources in a single call.

Error Handling:

  • If the request size is greater than 5 MB, then the operation fails with the HTTP status '413 Request entity too large' error.
  • If the request body in JSON is invalid in terms of the swagger schema, then the operation fails with the HTTP status '400 Bad Request' error. The error details are as follows:
    • Invalid property value. Path: 'path_in_swagger_shema'. Value: 'error_value'. Valid values: 'some_valid_value_1','some_valid_value_N'.
  • If both the parameters 'resourceId' and 'resourceInternalId' are specified in a request, then the operation fails with the HTTP status '400 Bad Request' error. The error details are as follows:
    • Only one of the parameters 'resourceId' or 'resourceInternalId' can be specified in a request.
  • If the parameters 'resourceId' and 'resourceInternalId' are missing in the request item, then the operation fails with the HTTP status '400 Bad Request' error. The error details are as follows:
    • Mandatory property is absent: 'resourceId' or 'resourceInternalId' must be defined.
  • If the swagger validation fails, then the operation fails with the HTTP status '400 Bad Request' error. Examples of such cases are:
    • A required field is not specified.
    • The request is not a valid JSON.
  • The operation returns HTTP status '200 OK', even if some work schedules are not updated or some resources specified in the request are invalid. Verify the response to identify the operations that succeeded and the operations that failed. The following is an example of such case:
    • The resourceId does not exist.

Permissions:

The permission 'core_api_resource' has to be set to 'ReadWrite' for this API to work.

Request

Body ()
Root Schema : Bulk Update Resource Work Schedules Schema
Type: array
Title: Bulk Update Resource Work Schedules Schema
Show Source
Nested Schema : Work Schedule
Type: object
Title: Work Schedule
An object containing a work schedule item.
Show Source
  • Title: Resource ID
    Minimum Length: 1
    Maximum Length: 32
    The identifier of the resource in the external system.

    Note: Only one of the following properties must be specified:

    • resourceId
    • resourceInternalId
  • Title: Resource Internal ID
    Minimum Value: 1
    The unique identifier of the resource in Oracle Field Service Cloud.

    Note: Only one of the following properties must be specified:

    • resourceId
    • resourceInternalId
  • Items
    Title: Items
    An array of work schedule items.
Nested Schema : Items
Type: array
Title: Items
An array of work schedule items.
Show Source
Nested Schema : Resource Work Schedule Item
Type: object
Title: Resource Work Schedule Item
The array of work schedule item of the resource.
Show Source
  • Title: Comments
    The description of the schedule in Oracle Field Service Cloud.
  • Title: End Date
    The date when this schedule ends. The date is in 'YYYY-MM-DD' format.
  • Title: Is Working Shift
    Contains one of the following values: true or false. If true, then it is a working day. If false, then it is a non-working day.

    This is a read-only field calculated based on the record type or the shift settings.

  • Title: Non-working Reason
    The reason for the non-working day (for example, holiday, vacation). These reasons are preconfigured in the Oracle Field Service Cloud UI.
  • Title: Points
    The units of labor per day when this schedule is in effect. This property may be empty because all the customers may not use it.
  • Title: Record Type
    Allowed Values: [ "schedule", "shift", "extra_shift", "working", "extra_working", "non-working" ]
    The type of work schedule record.
  • Recurrence
    Title: Recurrence
    An array containing recurring work schedule items. This object is optional when the recordType is schedule. And it is mandatory when the recordType is shift, extra_shift, working, extra_working or non-working
  • Title: Work Schedule Item ID
    The identifier of the work schedule item in Oracle Field Service Cloud.
  • Title: Work Schedule Label
    The label of the work schedule in Oracle Field Service Cloud. This property is only available if the record type is schedule.
  • Shifts
    Title: Shifts
    The list of work shifts present in this work schedule. The properties of the work shifts are for information purpose only and cannot be modified using this operation.
  • Title: Work Shift Label
    The label of the work shift in Oracle Field Service Cloud. This property is only available if the value of recordType is either shift or extra_shift.
  • Title: Shift Type
    Allowed Values: [ "regular", "on-call" ]
    The type of the work shift.
  • Title: Start Date
    The date when this schedule takes effect. The format is 'YYYY-MM-DD'.
  • Title: Work Time End
    The end time of the working day when this schedule is in effect. The format is 'HH:MM'. This property is not available if the value of the isWorking parameter is false.
  • Title: Work Time Start
    The start time of the working day when this schedule is in effect. The format is 'HH:MM'. This property is not available if the value of the isWorking parameter is false.
Nested Schema : Recurrence
Type: object
Title: Recurrence
An array containing recurring work schedule items. This object is optional when the recordType is schedule. And it is mandatory when the recordType is shift, extra_shift, working, extra_working or non-working
Show Source
  • Title: Day From
    The start day (in 'YYYY-MM-DD' format) of the schedule period applicable for each year, when the schedule is in effect. It is used only if the recurrence type is yearly.
  • Title: Day To
    The end day (in 'YYYY-MM-DD' format) of the schedule period applicable for each year, when the schedule is in effect. It is used only if the recurrence type is yearly.
  • Title: Recur Every
    Minimum Value: 1
    Maximum Value: 255
    The time between each recurrence of the work schedule. Depending on the value selected for 'recurrence', the value of the parameter indicates the time between recurrence in days or weeks. For example, if '4' is the value of this parameter, and the 'recurrence' is 'daily', it indicates that the time between each recurrence is four days.
  • Title: Recurrence Type
    Allowed Values: [ "daily", "weekly", "yearly", "everyday" ]
    The type of the recurrence. This property along with the 'recurEvery' property defines the time between each recurrence. For example, if the value of this property is 'daily' and the value of the property 'recurEvery' is '4', then the time between each recurrence is four days.
  • Recurrence Weekdays
    Title: Recurrence Weekdays
    The weekdays on which the work shift recurs.
Nested Schema : Shifts
Type: array
Title: Shifts
The list of work shifts present in this work schedule. The properties of the work shifts are for information purpose only and cannot be modified using this operation.
Show Source
Nested Schema : Recurrence Weekdays
Type: array
Title: Recurrence Weekdays
The weekdays on which the work shift recurs.
Show Source
  • Title: Weekday
    Allowed Values: [ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ]
    The weekday on which the work shift recurs. This field is required only if the recurrence type is weekly.
Nested Schema : Resource Shift Item
Type: object
Title: Resource Shift Item
An object containing the resource shift item.
Show Source
  • Title: Comments
    The description of this shift in Oracle Field Service Cloud.
  • Title: End Date
    The date when this shift ends. The date is in 'YYYY-MM-DD' format.
  • Title: Is Working Shift
    Contains one of the following values: true or false. If true, then it is a working day. If false, then it is a non-working day.

    This is a read-only field calculated based on the record type or the shift settings.

  • Title: Non-working Reason
    The reason for the non-working day (for example, holiday, vacation). These reasons are preconfigured in the Oracle Field Service Cloud UI.
  • Title: Points
    The units of labor per day when this schedule is in effect. This property may be empty because all the customers may not use it.
  • Title: Record Type
    Allowed Values: [ "shift", "extra_shift" ]
    The type of the work shift record.
  • Recurrence
    Title: Recurrence
    An array containing recurring work schedule items. For repeating shifts this property contains a description of how the shift repeats over time.
  • Title: Work Schedule Item ID
    The identifier of the work schedule item in Oracle Field Service Cloud.
  • Title: Work Schedule Label
    The label of the work schedule in Oracle Field Service Cloud. This property is only available for the record type schedule.
  • Title: Work Shift Label
    The label of the work shift in Oracle Field Service Cloud. This property is only available if the record type is either shift or extra_shift.
  • Title: Shift Type
    Allowed Values: [ "regular", "on-call" ]
    The type of the work shift.
  • Title: Start Date
    The date when this shift takes effect. The date is in 'YYYY-MM-DD'.
  • Title: Work Time End
    The end time of a working day when this work shift is in effect. The format is HH:MM. This property is not available if the value of the isWorking parameter is false.
  • Title: Work Time Start
    The start time of a working day when this work shift is in effect. The format is HH:MM. This property is not available if the value of the isWorking parameter is false.
Nested Schema : Recurrence
Type: object
Title: Recurrence
An array containing recurring work schedule items. For repeating shifts this property contains a description of how the shift repeats over time.
Show Source
  • Title: Day From
    The start day (in 'YYYY-MM-DD' format) of the schedule period applicable for each year, when the schedule is in effect. It is used only if the recurrence type is yearly.
  • Title: Day To
    The end day (in 'YYYY-MM-DD' format) of the schedule period applicable for each year, when the schedule is in effect. It is used only if the recurrence type is yearly.
  • Title: Recur Every
    Minimum Value: 1
    Maximum Value: 255
    The time between each recurrence of the work shift. Depending on the value selected for 'recurrence', the value of the parameter indicates the time between recurrence in days or weeks. For example, if '4' is the value of this parameter, and the 'recurrence' is 'daily', it indicates that the time between each recurrence is four days.
  • Title: Recurrence Type
    Allowed Values: [ "daily", "weekly", "yearly", "everyday" ]
    The type of the recurrence. This property along with the 'recurEvery' property defines the time between each recurrence. For example, if the value of this property is 'daily' and the value of the property 'recurEvery' is '4', then the time between each recurrence is four days.
  • Recurrence Weekdays
    Title: Recurrence Weekdays
    The weekdays on which the work schedule recurs.
Nested Schema : Recurrence Weekdays
Type: array
Title: Recurrence Weekdays
The weekdays on which the work schedule recurs.
Show Source
  • Title: Weekday
    Allowed Values: [ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ]
    The weekday on which the work schedule recurs.
Back to Top

Response

Supported Media Types

200 Response

This section describes the 200 status response for this operation.
Body ()
Root Schema : Resource Work Schedules Bulk Update Schema
Type: object
Title: Resource Work Schedules Bulk Update Schema
Show Source
Nested Schema : Results
Type: array
Title: Results
An array containing the results of the operation.
Show Source
Nested Schema : Result Item
Type: object
Title: Result Item
An object containing a single result item.
Show Source
Nested Schema : Errors
Type: array
Title: Errors
The errors that occurred while updating the work schedules of resources.
Show Source
Nested Schema : Error
Type: object
Error response
Show Source

Default Response

This section describes the default error response for this operation.
Body ()
Root Schema : Error
Type: object
Error response
Show Source
Back to Top

Examples

The following example shows how to bulk update resource work schedules by submitting a POST request on the REST resource using cURL:

cURL Command Example

curl -s -u "<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>" --url "https://<instance_name>.etadirect.com/rest/ofscCore/v1/resources/custom-actions/bulkUpdateWorkSchedules" -X POST -d '[
    {
        "resourceId": "test_bucket",
        "workSchedules": [
            {
                "recordType": "working",
                "startDate": "2018-04-16",
                "endDate": "2018-04-17",
                "workTimeStart": "10:00:00",
                "workTimeEnd": "22:00:00",
                "shiftType": "regular",
                "recurrence": {
                    "recurrenceType": "weekly",
                    "recurEvery": 5
                },
                "comment": "default test_bucket resources work schedule"
            },
            {
                "recordType": "schedule",
                "startDate": "2018-04-16",
                "endDate": "2018-04-17",
                "scheduleLabel": "On-call+2nd"
            },
            {
                "startDate": "2018-04-16",
                "endDate": "2018-04-17",
                "recordType": "non-working",
                "scheduleLabel": "On-call+2nd",
                "nonWorkingReason": "day-off"
            },
            {
                "recordType": "schedule",
                "startDate": "2018-04-16",
                "endDate": "2018-04-17",
                "scheduleLabel": "PAR-2nd/ODD-1st"
            }
        ]
    },
    {
        "resourceId": "test_tech",
        "workSchedules": [
            {
                "startDate": "2018-04-16",
                "endDate": "2018-04-17",
                "recordType": "schedule",
                "scheduleLabel": "PAR2nd/ODD-1st"
            }
        ]
    }
]'

Response Header Example

The following shows an example of the response header.

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Wed, 27 Jun 2018 12:44:50 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive

Response Body Example

The following shows an example of the response body in JSON format.

{
    "resourcesUpdated" : 1,
    "results" : [
        {
            "resourceId": "resource1",
            "itemsUpdated" : 3,
            "itemsFailed": 1,
            "errors": [
                {
                    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
                    "title": "Bad request",
                    "status": "400",
                    "detail": "Invalid schedule label \"PAR2nd/ODD-1st\""
                },
                {
                    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
                    "title": "Bad Request",
                    "status": "400",
                    "detail": "Required property not set. Entity: Resource Work Schedule, Property: shiftType"
                }
            ]
        },
        {
            "resourceId": "resource2",
            "itemsUpdated" : 0,
            "itemsFailed": 1,
            "errors":[{
                "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
                "title": "Bad request",
                "status": "400",
                "detail": "Invalid schedule label \"PAR2nd/ODD-1st\""
            }]
        },
        {
            "resourceId": "resource3",
            "itemsUpdated" : 3,
            "itemsFailed": 0
        }
    ]
}
Back to Top