Get calendars

get

/rest/ofscCore/v1/calendars

This operation retrieves the list of work schedules assigned to the specified resource for the specified duration. Use this operation to render the resource's work schedules on a calendar view control, such as a monthly view or a weekly view.

Work schedules represent a resource's work calendar, which includes working hours, working and non-working days, reasons for absence, and so on.

Note: Work schedules configured for parent resources are retrieved only if Oracle Field Service Cloud supports them.

Error Handling:

  • If the swagger validation fails, then the entire request fails with the HTTP status '400 Bad Request' error. For example, the swagger validation fails if a required field is not specified in the request.
  • In all other cases, the operation returns '200 OK'.

Permissions:

You must grant permissions to the Core API and must set Read-Write access to the Resource type entity in the Configuration, Applications (API permissions) screen.

Limits:

The date range in a request shouldn't exceed 31 days, otherwise an error is returned.

Errors Matrix:

  • Returns error 404 if any of the resources do not exist.
  • Returns error 400 if any of the following parameters are in an incorrect format:
    • dateFrom
    • dateTo
    • includeChildren
    • includeInactive
  • Returns error 400 if the value of the dateFrom parameter is greater than the value of the dateTo parameter.
  • Returns error 400 if the date range (dateFrom-dateTo) in the request is greater than 31 days.
  • Returns error 409 if the dates specified in the request are too far in the past, or in the future.

Request

Supported Media Types
Query Parameters
  • The date from which the work schedule is retrieved. Specify the date in YYYY-MM-DD format.
  • The date till when the work schedule is retrieved. Specify the date in YYYY-MM-DD format.
  • Indicates whether the subordinate resources must be returned.
    • If the value is none, then only the calendars of the specified resource are returned.
    • If the value is immediate, then the calendars of the specified resource and its first level descendants are returned.
    • If the value is all or if it is not specified, then the calendars of the specified resource and its descendants in the hierarchy tree are returned.
    Allowed Values: [ "none", "immediate", "all" ]
  • Indicates whether the calendars of the inactive resources must be returned.
    • If the value is true, then the calendars of the inactive resources are returned.
    • If the value is false, then the calendars of the inactive resources are not returned.
    Allowed Values: [ "true", "false" ]
  • The number of items to be returned in the response. The minimum value that can be specified is 1 and the maximum value that can be specified is 100. If the specified value is greater than 100, then it defaults to 100. Value less then 1 is not allowed.
  • The record number from which the retrieval starts. The default value is zero. If no value is specified, then it defaults to zero. The value zero indicates that the retrieval will start from the beginning of the collection.
  • Collection Format: csv
    The comma-separated list of resource IDs that are returned in the response. This parameter works in conjunction with the includeChildren parameter.
Back to Top

Response

Supported Media Types

200 Response

This section describes the 200 status response for this operation.
Body ()
Root Schema : getCalendarsResponse
Type: object
Show Source
Nested Schema : items
Type: array
A collection of calendar items.
Show Source
Nested Schema : getCalendarsResponseItem
Type: object
An array of resource calendar items.
Show Source
Nested Schema : calendarItem
Type: object
An object containing one calendar item. This calendar item is a data structure that contains information about the resource's regular and on-call shifts.
Show Source
  • Title: Comments
    The description of this work schedule item in Oracle Field Service Cloud.
  • Title: Non-working Reason
    The reason for a non-working day (for example, holiday, vacation). These reasons are preconfigured in the Oracle Field Service Cloud UI.
  • Title: Record Type
    Allowed Values: [ "schedule", "shift", "extra_shift", "working", "extra_working", "non-working" ]
    The type of this work schedule item.
  • Title: Work Time End
    The end time of a work day when this work schedule is in effect. The format is HH:MM. This property is not available if recordType='non-working'.
  • Title: Work Time Start
    The start time of a work day when this work schedule is in effect. The format is HH:MM. This property is not available if recordType='non-working'.

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 retrieve a list of work schedules by submitting a GET request on the REST resource using cURL:

cURL Command Example

curl -s -u 'clientId@instanceName:clientSecret' -X GET 'https://<instance_name>.etadirect.com/rest/ofscCore/v1/calendars?resources=routing&dateFrom=2018-07-04&dateTo=2018-07-05&includeChildren=all'

Response Header Example

The following shows an example of the response header.

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Mon, 18 Dec 2017 02:20:33 GMT
Content-Type: application/json; charset=utf-8

Response Body Example

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

{
    "items": [
        {
            "resourceId": "routing",
            "date": "2018-07-04",
            "regular": {
                "recordType": "working",
                "workTimeStart": "09:00",
                "workTimeEnd": "18:00"
            }
        },
        {
            "resourceId": "11100",
            "date": "2018-07-04",
            "regular": {
                "recordType": "working",
                "workTimeStart": "09:00",
                "workTimeEnd": "18:00"
            }
        },
        {
            "resourceId": "11101",
            "date": "2018-07-04",
            "regular": {
                "recordType": "working",
                "workTimeStart": "12:00",
                "workTimeEnd": "17:00",
                "points": 100,
                "shiftLabel": "12-17",
                "scheduleLabel": "12-17"
            }
        },
        {
            "resourceId": "11102",
            "date": "2018-07-04",
            "regular": {
                "recordType": "working",
                "workTimeStart": "12:00",
                "workTimeEnd": "17:00",
                "points": 100,
                "shiftLabel": "12-17",
                "scheduleLabel": "12-17"
            }
        },
        {
            "resourceId": "11103",
            "date": "2018-07-04",
            "regular": {
                "recordType": "working",
                "workTimeStart": "12:00",
                "workTimeEnd": "17:00",
                "points": 100,
                "shiftLabel": "12-17",
                "scheduleLabel": "12-17"
            }
        }
    ]
}
Back to Top