Jump to

• Request
• Response
• Examples

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 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

• application/x-www-form-urlencoded

Query Parameters

• dateFrom(required): string
  The date from which the work schedule is retrieved. Specify the date in YYYY-MM-DD format.
• dateTo(required): string
  The date till when the work schedule is retrieved. Specify the date in YYYY-MM-DD format.
• includeChildren: string
  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" ]
• includeInactive: string
  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" ]
• limit: integer
  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.
• offset: integer
  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.
• resources(required): array[string]
  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

• application/json

200 Response

This section describes the 200 status response for this operation.

Body ()

Root Schema : getCalendarsResponse

Type: object

Show Source

• items: array items
  A collection of calendar items.

{
    "properties":{
        "items":{
            "type":"array",
            "description":"A collection of calendar items.",
            "items":{
                "$ref":"#/definitions/getCalendarsResponseItem"
            }
        }
    }
}

Nested Schema : items

Type: array

A collection of calendar items.

Show Source

• Array of: object getCalendarsResponseItem
  An array of resource calendar items.

{
    "type":"array",
    "description":"A collection of calendar items.",
    "items":{
        "$ref":"#/definitions/getCalendarsResponseItem"
    }
}

Nested Schema : getCalendarsResponseItem

Type: object

An array of resource calendar items.

Show Source

• date: string
  Title: Date

  The date when this work schedule takes effect. The format is YYYY-MM-DD.
• on-call: object calendarItem
  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.
• regular: object calendarItem
  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.
• resourceId: string
  Title: Resource ID

  The unique identifier of the resource in Oracle Field Service.

{
    "type":"object",
    "description":"An array of resource calendar items.",
    "properties":{
        "resourceId":{
            "type":"string",
            "description":"The unique identifier of the resource in Oracle Field Service.",
            "title":"Resource ID"
        },
        "date":{
            "type":"string",
            "description":"The date when this work schedule takes effect. The format is YYYY-MM-DD.",
            "title":"Date"
        },
        "regular":{
            "$ref":"#/definitions/calendarItem"
        },
        "on-call":{
            "$ref":"#/definitions/calendarItem"
        }
    }
}

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

• comments: string
  Title: Comments

  The description of this work schedule item in Oracle Field Service.
• nonWorkingReason: string
  Title: Non-working Reason

  The reason for a non-working day (for example, holiday, vacation). These reasons are preconfigured in the Oracle Field Service UI.
• recordType: string
  Title: Record Type

  Allowed Values: [ "schedule", "shift", "extra_shift", "working", "extra_working", "non-working" ]

  The type of this work schedule item.
• workTimeEnd: string(time)
  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'.
• workTimeStart: string(time)
  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'.

{
    "type":"object",
    "description":"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.",
    "properties":{
        "recordType":{
            "type":"string",
            "enum":[
                "schedule",
                "shift",
                "extra_shift",
                "working",
                "extra_working",
                "non-working"
            ],
            "description":"The type of this work schedule item.",
            "title":"Record Type"
        },
        "comments":{
            "type":"string",
            "description":"The description of this work schedule item in Oracle Field Service.",
            "title":"Comments"
        },
        "workTimeStart":{
            "type":"string",
            "format":"time",
            "description":"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'.",
            "title":"Work Time Start"
        },
        "workTimeEnd":{
            "type":"string",
            "format":"time",
            "description":"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 End"
        },
        "nonWorkingReason":{
            "type":"string",
            "description":"The reason for a non-working day (for example, holiday, vacation). These reasons are preconfigured in the Oracle Field Service UI.",
            "title":"Non-working Reason"
        }
    }
}

Default Response

This section describes the default error response for this operation.

Body ()

Root Schema : Error

Type: object

Show Source

• detail: string
  The detailed description of this error.
• status: string
  The HTTP status code of this error.
• title(required): string
  The brief description of this error.
• type(required): string
  The URL of the web page containing more details about this error.

{
    "properties":{
        "type":{
            "type":"string",
            "description":"The URL of the web page containing more details about this error."
        },
        "title":{
            "type":"string",
            "description":"The brief description of this error."
        },
        "status":{
            "type":"string",
            "description":"The HTTP status code of this error."
        },
        "detail":{
            "type":"string",
            "description":"The detailed description of this error."
        }
    },
    "required":[
        "type",
        "title"
    ]
}

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>.fs.ocs.oraclecloud.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