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

Show booking grid

post

/rest/ofscCapacity/v1/showBookingGrid

This operation retrieves the booking grid 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 time slots must satisfy the constraints specified in the company configuration
  • The booking is not closed for the category, time frame, and work zone.
  • The workforce is available to perform the activity.

Time slots filtering

The filtering of time slots during the showBookingGrid API call is intended to prepare a preliminary set of time slots that will be used in the next check for the possibility of booking the required activity. This filtering is performed in two steps:

  1. We obtain a set of pairs time slot - capacity category that simultaneously satisfy the company restrictions and the set of capacity categories required according to the request data. All capacity categories required according to the request data must be assigned to the time slot.
  2. For each capacity area that can be mentioned in the response, we select only those items (and as a result, time slots) from the first set of pairs where the capacity category is contained in the capacity area configuration.

Recommendations

The function may provide recommendations to select more preferable time-slots for activity booking that reduce overall travel expenses.

To get the recommendations in the response:

  • Enable this ability in the capacity area configuration.
  • Ensure that, in the request, you include enough information that the application uses to calculate the distances / travel to other activities. This is the latitude and longitude fields for booking by Capacity / Quota, or the fields configured as the activity travel key in case of direct assignment booking.

For more information about booking recommendations, see the Booking Recommendations chapter in the Using Capacity Service guide.

Request

Body ()
Root Schema : showBookingGridSchema
Type: object
Show Source
  • Activity object
    Title: Activity object

    The activity object for which booking grid should be shown.
    It should contain either:

    • Keys of an already existing activity in the system
    • Activity fields values

    To specify an already existing activity key values should be provided depending on 'identifyActivityBy' parameter. The following fields in activity object are mandatory:

    • when identifyActivityBy is 'activityId' - activityId
    • when identifyActivityBy is 'apptNumber' - apptNumber
    • when identifyActivityBy is 'apptNumberPlusCustomerNumber' - apptNumber and customerNumber

    To specify a not yet created activity all fields necessary for booking must be provided. Mandatory elements are:

    • All fields that are needed to identify activity work skills and work zones (if used)
    • activityType - Type of the activity
    • timeZone - Customer time zone

    Optionally, in order to obtain the booking recommendations, you will need to include enough information that the application uses to calculate the distances / travel to other activities. This is the latitude and longitude fields for booking by Capacity / Quota, or the fields configured as the activity travel key in case of direct assignment booking.

  • The date from which the booking options will be searched.
    Example: 2019-02-18

  • The date to which the booking options will be searched.

    • Minimum value: (dateFrom).
    • Maximum: (dateFrom + 14 days).
    • Default value: (dateFrom + 7 days).
    Example: 2019-09-29
  • Forecast During Booking
    Title: Forecast During Booking
    The criteria used to sort and filter the results by means of forecasting the future activity flow to calculate the average additional travel per activity.

    Results with travel more then an average per bucket are filtered out before the end of forecasting period. If a particular parameter is not present or not specified in request, then the default values are applied.

  • Allowed Values: [ "activityId", "apptNumber", "apptNumberPlusCustomerNumber" ]

    If this parameter is absent, then the 'activity' parameter should contain all activity fields necessary for booking.

    If this parameter is present then the 'activity' parameter should contain the activity key fields, that identify an already existing activity.

  • Default Value: false
    The parameter which indicates whether to return the dictionary of all resources in the response.
  • Default Value: false
    The parameter which indicates whether to return the dictionary of time slots in the response.
  • Title: Activity late start mitigation
    Default Value: 20
    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
  • resourceFields
    The list of names of the resource fields and properties to be added to the each resource in the dictionary. Available fields are 'resourceId', 'parentResourceId', 'resourceType', 'name', 'email', 'phone', 'timeZone', 'status'. Custom properties are allowed.
  • Default Value: false

    If this parameter is 'true' then the function returns all options including unavailable for booking and provide the reason message indicating why an option is not available.
    If this parameter is 'false' or absent, only options that allow booking will be returned.

Nested Schema : Activity object
Type: object
Title: Activity object

The activity object for which booking grid should be shown.
It should contain either:

  • Keys of an already existing activity in the system
  • Activity fields values

To specify an already existing activity key values should be provided depending on 'identifyActivityBy' parameter. The following fields in activity object are mandatory:

  • when identifyActivityBy is 'activityId' - activityId
  • when identifyActivityBy is 'apptNumber' - apptNumber
  • when identifyActivityBy is 'apptNumberPlusCustomerNumber' - apptNumber and customerNumber

To specify a not yet created activity all fields necessary for booking must be provided. Mandatory elements are:

  • All fields that are needed to identify activity work skills and work zones (if used)
  • activityType - Type of the activity
  • timeZone - Customer time zone

Optionally, in order to obtain the booking recommendations, you will need to include enough information that the application uses to calculate the distances / travel to other activities. This is the latitude and longitude fields for booking by Capacity / Quota, or the fields configured as the activity travel key in case of direct assignment booking.

Show Source
  • Title: Activity ID
    The unique identifier of the activity.
  • Title: Activity Type
    The label of the activity type.
  • Title: Appointment Number
    This field 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 can be left empty. Maximum field length is 40.
  • Title: Customer Number
    The account number of the customer. This field 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. Maximum field length is 40. If a longer value is sent it will be truncated.
  • Title: Time Zone
    The name of the customer's time zone. For example, Eastern.

    By default, the time zone of the resource to which the activity is assigned is used.

    For a list of supported time zones, see Supported Time Zones.

Nested Schema : Forecast During Booking
Type: object
Title: Forecast During Booking
The criteria used to sort and filter the results by means of forecasting the future activity flow to calculate the average additional travel per activity.

Results with travel more then an average per bucket are filtered out before the end of forecasting period. If a particular parameter is not present or not specified in request, then the default values are applied.

Show Source
  • Title: Maximum Forecast Range Day
    Minimum Value: 0
    Maximum Value: 31
    Number of days, counted from current day, where current day is 0. Should be greater then Minimum Forecast Range Day. System does the activity flow forecasting between Minimum Forecast Range Day and Maximum Forecast Range Day. During this period the average additional travel is calculated based on the number of the forecasted activities within the close proximity of the activity being booked and only results having the additional travel lesser then the average per-bucket travel are returned. After the Maximum Forecast Range Day all the available results are returned, despite the additional travel. No activity flow forecasting is done after Maximum Forecast Range Day.
  • Title: Minimum Forecast Range Day
    Minimum Value: 0
    Maximum Value: 31
    Number of days, counted from current day, where current day is 0. before which only results that has an existing activity within the close proximity are returned. No activity flow forecasting is done before Minimum Forecast Range Day.
  • Title: Optimization Goal
    Allowed Values: [ "default", "minimizeAdditionalTravel" ]
    Choose minimizeAdditionalTravel to sort the results by increasing of additional travel added. Default option sorts the results by ETA from minimal to maximal.
  • Title: Enable Forecast During Booking
    Turn on to sort and filter the results by means of forecasting the future activity flow to calculate the average additional travel per activity.
Nested Schema : resourceFields
Type: array
The list of names of the resource fields and properties to be added to the each resource in the dictionary. Available fields are 'resourceId', 'parentResourceId', 'resourceType', 'name', 'email', 'phone', 'timeZone', 'status'. Custom properties are allowed.
Show Source
Back to Top

Response

Supported Media Types

200 Response

This section describes the 200 status response for this operation.
Body ()
Root Schema : showBookingGrid
Type: object
Show Source
Nested Schema : areas
Type: array
The array of available booking options. Each item in the array contains the available booking options for a capacity area.
Show Source
Nested Schema : resourcesDictionary
Type: array
An array of resource items. Depend on 'resourceFields' parameter the field set of resource object may vary.
Show Source
  • resource
    Title: resource
    The resource used for an activity. For example, a resource can be a technician, a truck, or a bucket.

    Note: This resource is not the same as a REST resource.

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 : area
Type: object
Title: area
Show Source
  • areaTimeSlots
    The list of time slot labels which are specified for the area.
  • Title: Average Travel Time On The Technician Bucket
    Contains the value of average travel time over the bucket.
  • Title: Average Travel Time On The FMR Activity Travel Key
    Contains the value of average travel time for the traveling withing the same travel key as of bookable activity.
  • The external identifier of a bucket that represents a Capacity Area.
  • dates
    The array of available booking options. Each item in the array contains the available booking options for a particular day.
  • The label of the area.
  • The name of the area.
  • 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.
Nested Schema : areaTimeSlots
Type: array
The list of time slot labels which are specified for the area.
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 : date
Type: object
Title: date
Show Source
  • An item of the array that contains data for a single day.
    Example: 2016-07-22
  • Title: Contains Forecasted Activities
    Contains one of the following values: true or false. If true, the activity flow forecast was used to calculate the additional travel. If false, then only activities already present in the route were used to calculate the additional travel.
  • Title: Contains Nearby Activities
    Contains one of the following values: true or false. If true, either the previous or the following activity is in close proximity of the activity specified in request. If false, then the previous or the following activity is not in close proximity of the activity specified in request.
  • The quota value that is defined on a day level. For interval-based booking, if there is no quota defined, this parameter is not returned.
  • 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 time zone difference in minutes for current capacity area (according to configured time zone) for current date.
Nested Schema : timeSlots
Type: array
The list of time slots at which the activity can be started.
Show Source
Nested Schema : timeSlot
Type: object
Title: timeSlot
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 booking.
  • Allowed Values: [ "timeInPast", "noCapacity", "closedTimeSlot", "allCategoriesAreClosed", "tooLongTravel" ]

    This value may be returned if the request parameter returnReasons: true was specified. It is returned for the options that should not be used for booking and contains the reason why.

    The meaning of the values:

    • timeInPast: This time slot is already in the past;
    • noCapacity: For the time-slot based booking: Quota is exceeded on some level(s); For other booking types: activity cannot be assigned to this time slot without violating time constraints;
    • closedTimeSlot: For the time-slot based booking only: the time slot has been closed in the booking status;
    • allCategoriesAreClosed: For the time-slot based booking only: all the Capacity Categories have been closed.
    • tooLongTravel: additionalTravel exceeds averageBucketTravel by more than 20%, and there is no travelKeyMatch (If the "Using forecasted activities flow" option is activated either through the GUI or API parameters)
  • recommendationInfo
    This structure is provided for options that are recommended by the system.
  • The available quota after activity booking. If there are multiple constraints (for example, day and category quota), the minimal quota value is returned. The parameter is returned only for timeslot-based booking.
  • Title: Resource ID
    The unique identifier of the resource in Oracle Field Service.
  • setPositionInRoute
    The value of this element determines the position of the activity in the route. If this element is present then activity will be put to specified position in route. The parameter is optional, if it is absent then the value "position: byServiceWindow" is used.
Nested Schema : recommendationInfo
Type: object
This structure is provided for options that are recommended by the system.
Show Source
  • Title: Additional Travel
    The difference in minutes between total travel in the current route and travel in the proposed route where the booking activity added.
  • Allowed Values: [ "good", "best" ]
    This attribute may be used in user interfaces for booking to mark the options with two levels of recommendations.
  • The distance in kilometers to the nearby activity (e.g. 'nearbyDistance': 12.5). This value is provided for Capacity Areas with Quota based booking.
  • The estimated travel time in minutes to or from the nearby activity. This value is provided for Capacity Areas with Direct Assignment based booking.
  • Title: Travel Key Match
    Contains one of the following values: true or false. If true, either the previous or the following activity has the same travel travel key value as the activity specified in request. If false, then the previous or the following activity has the different travel travel key values as the activity specified in request.
Nested Schema : setPositionInRoute
Type: object
The value of this element determines the position of the activity in the route. If this element is present then activity will be put to specified position in route. The parameter is optional, if it is absent then the value "position: byServiceWindow" is used.
Show Source
  • Title: Activity ID
    The unique identifier of some pending ordered activity in the target route. It is used along with the 'afterActivity' value of the 'position' parameter so that to put one activity in the position after another.
  • Title: Position
    Allowed Values: [ "first", "last", "notOrdered", "byServiceWindow", "afterActivity" ]
    The position of the activity in the route.
Nested Schema : resource
Type: object
Title: resource
The resource used for an activity. For example, a resource can be a technician, a truck, or a bucket.

Note: This resource is not the same as a REST resource.

Show Source
  • Title: Email
    The email ID of the resource. The maximum character length of this field is 255 characters. If more than 255 characters are specified, then only the first 255 characters are saved and the rest are ignored.
  • Title: Name
    Minimum Length: 1
    The name of the resource. The maximum character length of this field is 40 characters. If more than 40 characters are specified, then only the first 40 characters are saved and the rest are ignored.
  • Title: Parent Resource ID
    The unique identifier of the parent resource.
  • Title: Phone

    The phone number of the resource. The maximum character length of this field is 16 characters. If more than 16 characters are specified, then only the first 16 characters are saved and the rest are ignored.

    Note: The phone number is saved in Oracle Field Service with the '+' symbol and all other non-digit characters are removed. For example, if you enter the phone number as +1(234)234-23_42, it is saved in Oracle Field Service as +12342342342.

  • Title: Resource ID
    The identifier of the resource in the external system. The maximum character length of this field is 32 characters. If more than 32 characters are specified, the operation fails with HTTP status 400 error.
  • Title: Resource Type
    The type of the resource.
  • Title: Status
    Allowed Values: [ "active", "inactive" ]
    The status of the resource.
  • Title: Time Zone
    The name of the resource's time zone. This field accepts both Oracle Field Service time zone names (for example, Eastern) and IANA standard time zone names (for example, America/New_York). It is recommended that you specify IANA names. In the response, this field contains the Oracle Field Service time zone name, while the field 'timeZoneIANA' contains the IANA time zone name. For a list of supported time zones, see Supported Time Zones.
  • Title: Time Zone IANA Name
    The IANA name of the resource's time zone (for example, America/New_York). For the list of IANA time zone names, see IANA Time Zones

    This is a read-only field and is only returned in responses.

Nested Schema : time slot info
Type: object
Title: time slot info
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 find booking options for a new and an existing activity by submitting a POST request on the REST resource.

Examples of Request Header

cURL command for finding an existing booking activity

curl -X 'POST' \
-u '<CLIENT-ID@<INSTANCE-NAME>:<CLIENT-SECRET>' \
-H 'Content-Type: application/json' \
--data-binary '{
        "apptNumber": "W1212-44",
        "customerNumber": "98798022"
    },
    "identifyActivityBy": "apptNumberPlusCustomerNumber",
    "dateFrom": "2020-05-03"}'
}' \
'https'://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCapacity/v1/showBookingGrid'

cURL command for finding a new booking activity

POST /rest/ofscCapacity/v1/showBookingGrid
{
    "activity": {
        "duration":50,
        "activityType":"Installation",
        "city":"ALTAMONTE SPRINGS",
        "postalCode": "1234123"
    },
    "dateFrom": "2021-03-01"
}

Example of Request Body

The following example shows the direct assignment area bookings by submitting a POST request on the REST resource.

{ 
    "criteria": {
        "resourcePreference": 0.0,
        "workSkill": 100,
        "workTime": 100,
        "workZone": 100,
        "includeResources": "technicians"
    },
    "limit": 3,
{
    "duration": 26,
    "travelTime": 30,
    "workZone": "LONGWOOD",
    "timeSlotsDictionary": [...],
    "areas": [
        {
            "label": "far_far_away_region",
            "name": "TEXAS CITY",
            "bucket": "routing_bucket_T",
            "timeZone": "America/Chicago",
            "areaTeimSlots: [ "08-12", "12-15", "15-18" ],
            "dates": [
                {
                    "date": "2020-07-10",
                    "timeSlots": [
                        {
                            "label": "15-17",
                            "resourceId": "FieldResource_1231",
                            "setPositionInRoute": {
                                "position": "afterActivity",
                                "activityId": "31323287"
                            }
                        },
                        {
                            "label": "08-10",
                            "resourceId": "FieldResource_1231",
                            "setPositionInRoute": {
                                "position": "first"
                            }
                        }
                    ]
                },
                {
                    ...
                },
                ...
            ]
        }
    ]
}    "date": "2018-01-16",
    "fields": [
        "resourceId",
        "resourceType",
        "parentResourceId"
    ],
    "schedulesToReturn": [
        "2018-01-16"
    ],
    "activity": {
        "activityType": "default_customer_activity_type",
        "timeZone": "Eastern",
        "customerName": "fmr customer name",
        "city": "07158",
        "string_text_activity_property": "IN"
    }
}
Back to Top