1. REST API for Oracle Field Service Cloud Service
  2. Tasks
  3. Capacity
  4. Booking

Get activity booking options

get

/rest/ofscCapacity/v1/activityBookingOptions

This operation retrieves the available booking options (such as buckets and time slots) for booking an activity.

Overview

This operation retrieves the time slots in which the activity can be performed. The following points are considered while booking an activity within the time slots:

  • The booking quota is available for the category and for the day.
  • The booking is not closed for the category, time frame, and work zone.
  • The workforce is available to perform the activity.

Additionally, the StopBookingAt constraint is considered for activity booking in an availability-based quota bucket. The StopBookingAt value denotes the percentage of the quota used for a day and indicates that no more activities can be booked for the selected category, when the StopBookingAt percentage is reached.

Activity fields

This operation calculates the estimated travel time, duration, area, and capacity category for booking an activity based on the activity fields and custom properties request parameters. The built-in activity fields have the same names and the same format as in the other REST API operations. The following built-in fields are considered:

  • apptNumber
  • recordType
  • customerName
  • customerNumber
  • customerPhone
  • customerEmail
  • customerCell
  • streetAddress
  • city
  • postalCode
  • stateProvince
  • reminderTime
  • longitude
  • latitude
  • slaWindowStart
  • slaWindowEnd
  • points
  • timeOfBooking
  • language
  • timeZone
The custom properties are identified by their label and are same as in the other REST API operations.

Activity field requirements are as follows:

  • The 'work zone key' fields must be passed, if the 'determineAreaByWorkZone' parameter is not set to 'false' or if the bucket settings close bookings by work zone.
  • All fields mentioned in work skill conditions should be passed, if the 'determineCategory' parameter is set to 'true', else the category will not be determined.
  • The 'duration key' fields need to be passed, if the 'estimateDuration' parameter is set to 'true'.
  • If the 'estimateTravelTime' parameter is set to 'true', then, the 'travel key' fields need to be passed. If any field is not provided, then the value of that field will be considered as empty when calculating travel key. If 'Detect activity travel keys automatically' is checked in Statistics configuration, then it is recommended to pass country_code, city and postalCode.

For example: If the postal code/Zip code is configured as part of the travel key, then the ?postalCode=12345 can be specified as one of the query parameters.

Note:If any custom property label conflicts with another query parameter, then it will be ignored and cannot be used until renamed.

Request

Query Parameters
  • The type of the activity. Based on the activity type, predefined company-specific rules are applied while processing an activity. Predefined company-specific rules cover the following:
    • The resources to which the activities can be assigned.
    • The activity processing details.
    • The interaction of the activity with different modules of Oracle Field Service.
  • Maximum Length: 40
    The parameter may be used by integrations to store the identifier of the activity in the origin system. This field has no business significance in Oracle Field Service and may be left empty.
  • Collection Format: csv
    The labels of the capacity areas.

    Note: If the 'areas' parameter is not passed and if the 'determineAreaByWorkZone' parameter is set to 'false', then the operation processes all the visible capacity areas.

  • Collection Format: csv
    The labels of the capacity categories in the capacity category filter.
  • The city of the customer where the activity is scheduled. This field is used for geocoding and must contain a valid address.
  • The customer's cell phone number. From version 17.2.1, the phone number is saved in Oracle Field Service with the '+' symbol. For example, if you enter the phone number as +1(234)234-23_42, it is saved in Oracle Field Service as +12342342342.
  • The email address of the customer.
  • The name of the customer.
  • The account number of the customer. This parameter is used by integrations as a placeholder for the external identifier of the account ID in the application. This parameter has no business significance in Oracle Field Service and can be left empty.
  • The regular (land) phone number of the customer. From version 17.2.1, the phone number is saved in Oracle Field Service with the '+' symbol. For example, if you enter the phone number as +1(234)234-23_42, it is saved in Oracle Field Service as +12342342342.
  • Collection Format: csv
    The dates for which the booking options are requested. The dates are specified as a comma-separated list, for example, YYYY-MM-D1,YYYY-MM-D2,YYYY-MM-D3.
  • The duration value (in minutes) used in one of the following scenarios:
    • The 'Define duration manually' option is enabled for the activity type.
    • The 'estimateDuration' option is disabled.
    • The statistical record is not available for the activity.

    Note:If the 'estimateDuration' option is disabled and if the 'defaultDuration' value is not passed, then the duration of the activity to be booked is the default duration of the activity type.

  • Contains one of the following values: true or false.

    If true, then the work zone is determined automatically and all capacity areas or groups that have the work zone are processed.

    Note: The determination algorithm is based on the calculation of the work zone key (defined in the Company Settings, Work Zone Dictionary screen) and uses the specified activity fields and finds a zone that corresponds to the calculated value. Therefore, all the fields that are used to calculate the work zone key formula are mandatory.

    If false, then the capacity area or group is not determined by the work zone of the activity. The default value is true.

  • Contains one of the following values: true or false.

    If true, then all the included fields in the work skill conditions must be specified and these fields are required to determine work skills and capacity categories for booking the activity.

    Note: Contrary to the 'get_capacity' operation, this operation books activities that do not have capacity categories. Therefore, if the operation is unable to determine a capacity category using the specified fields, it does not return an error.

    If false, then the capacity categories are not determined based on the specified activity fields. The default value is true.

  • Contains one of the following values: true or false. If true and if the 'Define duration manually' option is disabled for a corresponding activity type, then the operation tries to estimate the duration of the activity using statistics.

    To estimate the activity duration, it is required to calculate the activity duration key. Therefore, all the fields that are used to calculate the activity duration key formula become mandatory.

    If the 'estimateDuration' option is enabled and the operation is unable to find a corresponding statistical record, then the following values are used:
    • The 'defaultDuration' parameter
      • OR
    • The default duration value defined on the activity type level.

    If false, then the operation does not estimate the duration of the activity using statistics. The default value is true.

  • Contains one of the following values: true or false.

    If true and the 'Calculate travel' option is set for a corresponding activity type, then the operation tries to estimate the activity travel time using statistics.

    To estimate the activity travel time, it is required to calculate the activity travel key. Therefore, all the fields used to calculate the activity travel key formula become mandatory.

    Note: The operation uses the same travel estimation algorithm for the activity located in the capacity area.

    If false, then the operation does not estimate the activity travel time using statistics. The default value is true.

  • Contains one of the following values: true or false. If true and if more than one capacity category matching the activity is defined for the capacity areas, then the operation returns capacity areas having at least one capacity category matching the activity.

    If false or not specified, then the operation returns only those capacity areas that have all the capacity categories matching the activity. The default value is false.

  • The preferred language of the customer. This parameter is optional and its value defaults to the language set for the Login screen. The accepted language codes are listed on: Supported Language Codes.
  • The ISO language code (for example, 'en-US').
  • Minimum Value: 0
    Maximum Value: 100
    Do not suggest booking options if the activity is likely to begin close to the end of the time slot within last [ NN ] percent. This functionality is only applicable for quota by intervals. Default: 20
  • Minimum Value: -90
    Maximum Value: 90
    The latitude coordinate (in degrees) of the activity.
  • Minimum Value: -180
    Maximum Value: 180
    The longitude coordinate (in degrees) of the activity.
  • The parameter is used for day-0 bookings. When it is specified, the operation only returns the intervals where the start time is greater than the sum of currentTime and minTimeBeforeArrival parameters.
  • Minimum Value: 0
    Maximum Value: 65535
    The cost of the activity in 'points'. This parameter is intended for use by the Routing module.
  • The postal code of the customer. This field is used for geocoding and must contain a valid address.
  • The type of the activity record. The following values are available:
    • regular: The default value for most new activities.
    • prework: The pre-work activity is created in Oracle Field Service, if the technician needs to perform some work before the actual activity.
    • reopened: The activity is created when an activity in a final status is reopened for some reason.
    • multiday_activity: The activity is created when the 'activityType' specified in the API indicates that it is a segmentable activity.
    • multiday_activity_segment: The activities that are automatically created for segmentable activities, based on their duration and timeslot settings.
    Allowed Values: [ "regular", "reopened", "prework", "multiday_activity", "multiday_activity_segment" ]
  • The number of minutes before the activity start time the customer must be notified of the activity.
  • The time when the Service Level Agreement (SLA) window ends. Specify the time in 'YYYY-MM-DD HH:MM:SS' format.
  • The time when the Service Level Agreement (SLA) window starts. Specify the time in 'YYYY-MM-DD HH:MM:SS' format.
  • The state or province of the customer. This field is used for geocoding and must contain a valid address.
  • The street address of the customer. This field is used for geocoding and must contain a valid address.
  • The time when the customer booked the activity. The time is displayed in the time zone of the customer.
  • The name of the customer's time zone.
Back to Top

Response

Supported Media Types

200 Response

This section describes the 200 status response for this operation.
Body ()
Root Schema : activityBookingOptions
Type: object
Show Source
Nested Schema : categories
Type: array
The array of capacity categories returned for the activity. Each item in the array indicates the label of the capacity category.
Show Source
Nested Schema : dates
Type: array
The array of available booking options. Each item in the array contains the available booking options for a particular day.
Show Source
Nested Schema : timeSlotsDictionary
Type: array
The dictionary of time slots on the top level, which includes all time slots defined for the capacity areas and filtered by defined capacity categories.
Show Source
Nested Schema : items
Type: object
Show Source
  • areas
    The array of available booking options within a capacity area for a single day.
  • An item of the array that contains data for a single day.
    Example: 2016-07-22
Nested Schema : areas
Type: array
The array of available booking options within a capacity area for a single day.
Show Source
Nested Schema : items
Type: object
Show Source
  • The external identifier of the bucket in which the booked activity is placed.
  • categories
    The list of capacity categories matching the activity for the capacity area. Each item in the list denotes a capacity category label. The parameter is returned only if the 'includePartiallyDefinedCategories' parameter in the request is set to true. The parameter is not returned when the booking is not allowed and when the 'reason' field is present.
  • The label of the area.
  • The name of the area.
  • The quota value which is defined on a day level.
  • Allowed Values: [ "noTimeZoneDiff", "dateInPast", "timeInPast", "allTimeSlotsAreClosed", "allCategoriesAreClosed", "closedDay", "closedCategory", "closedWorkZone", "stopBookingAt", "missingCategories", "undefinedQuota", "noCapacity" ]
    The reason for the unavailability of booking options. If there are multiple reasons, then only one reason is returned. The priority corresponds to the order of items in the list. The parameter is returned for the matched area where there are no available booking options.

    If the value of the stopBookingAt reason is defined, then the values for the originalQuota and remainingQuota parameters should be returned only for capacity areas.

  • The quota available on the day level after the activity booking. If there is no quota defined, the parameter is not returned.
  • timeSlots
    The list of time slots at which the activity can be started.
  • The IANA name (for example, 'America/New_York') of the time zone. If the IANA name is not defined for a given time zone (if the time zone differences are entered manually), then the operation returns a label or name of the time zone. The labels are used to identify the time zones in public API calls.
  • The time zone difference in minutes for current capacity area (according to configured time zone) for current date.
Nested Schema : categories
Type: array
The list of capacity categories matching the activity for the capacity area. Each item in the list denotes a capacity category label. The parameter is returned only if the 'includePartiallyDefinedCategories' parameter in the request is set to true. The parameter is not returned when the booking is not allowed and when the 'reason' field is present.
Show Source
Nested Schema : timeSlots
Type: array
The list of time slots at which the activity can be started.
Show Source
Nested Schema : items
Type: object
Show Source
  • The label of the time slot. The parameter is not returned for the custom service window.
  • The minimum quota value defined on a time slot level for activity fields or capacity categories. The parameter is returned only for timeslot-based quota.
  • Allowed Values: [ "timeInPast", "closedTimeInterval", "stopBookingAt", "closedTimeSlot", "closedCategory", "noCapacity" ]
    The reason the timeslot is not used for activity booking. The parameter is returned for a matched time slot that cannot be used for activity booking. It also contains a corresponding reason,for example, timeInPast, closedTimeInterval, stopBookingAt (time-slot based quota), closedTimeSlot (time-slot based quota), closedCategory (time-slot based quota; all required capacity categories within this time slot are closed), noCapacity.

    Note: If there are multiple reasons, only one reason is returned. The priority corresponds to the order of items in the list. Also, the parameter is returned only for the timeslot-based quota.

  • The available quota after activity booking. If there are multiple constraints (for example, day and category quota), the minimal quota value is returned. If there is no quota defined, then the parameter is not returned.
Nested Schema : items
Type: object
Show Source

Default Response

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

Examples

The following example shows how to get activity booking options by submitting a GET request on the REST resource using cURL. 

curl 'https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCapacity/v1/activityBookingOptions/
?dates=2018-02-10
&activityType=33
&postalCode=12345
&city=LONGWOOD
&determineAreaByWorkZone=true
&determineCategory=true
&WO_TYPE=1
&estimateDuration=true
&defaultDuration=30
&estimateTravelTime=true
&minTimeBeforeArrival=120
&includePartiallyDefinedCategories=true

Example of Response Body

The following example shows the contents of the response body in JSON format:

{
    "duration": 26,
    "travelTime": 30,
    "categories": [
        "IN",
        "DI"
    ],
    "workZone": "LONGWOOD",
    "timeSlotsDictionary": [
                        {
                            "label": "10-12"
                            "name": " 10:00-12:00AM",
                            "timeFrom": "10:00:00",
                            "timeTo": "12:00:00"
 
                        },
                        {
                            "label": "08-10"
                            "name": " 8:00-10:00AM",
                            "timeFrom": "08:00:00",
                            "timeTo": "10:00:00"
                        }
                    ]
    "dates": [
        {
            "date": "2018-02-10",
            "areas": [
                {
                    "label": "routing_bucket_T",
                    "name": "TEXAS CITY",
                    "bucket": "routing_bucket_T",
                    "timeZone": "America/Chicago",
                    "categories": [
                            "IN"
                    ],
                    "remainingQuota": 270,
                    "originalQuota": 500,
                    "timeSlots": [
                        {
                            "label": "15-17"
                        },
                        {
                            "label": "13-15"
                        },
                        {
                            "label": "10-12"
                        },
                        {
                            "label": "08-10"
                        }
                    ]
                },
                {
                    "label": "ASIA",
                    "name": "Asia",
                    "bucket": "ASIA",
                    "reason": "allTimeSlotsAreClosed"
                },
                {
                    "label": "EUROPE",
                    "name": "Europe",
                    "bucket": "EUROPE",
                    "reason": "allTimeSlotsAreClosed"
                },
                {
                    "label": "São José",
                    "name": "São José dos Campos",
                    "bucket": "São José",
                    "reason": "allTimeSlotsAreClosed"
                },
                {
                    "label": "routing",
                    "name": "Planning",
                    "bucket": "routing",
                    "reason": "allTimeSlotsAreClosed"
                }
            ]
        }
    ]
}
Back to Top