Find matching resources

post

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

This operation returns a list of resources which can complete this activity based on the criteria in the request. Only resources that match all of the criteria specified in request will be returned in response.

Overnight

Overnight is represented as ["FROM_TIME","TO_TIME"] where, the FROM_TIME is greater than the TO_TIME.

For example, ["12:00","10:00"] indicates that the provider working time is from 12:00 to 10:00 of the next day, that is, 22 hours.

Fitness formula for "workTime"

The length (in minutes) of intersection interval of "activity window" with "technician working schedule".

The parameter "activity window" is an intersection of SLA window and SW window for the parameter "date". If activity window is empty or undefined, then the value is equal to the duration of technicians working day.

Fitness formula for "workZone"

The Resource's workzone ratio for the activity workzone (0-100).
  • The value is 100 if the activity does not have a work zone (no work zone requirements).
  • The value is 0 if this resource does not have the activity's work zone assigned to it.
  • Else, the value is equal to the 'ratio' of the resource's assigned work zone.

Fitness formula for "workSkill"

  • The value is 100 if:
    • the activity does not have any work skill requirements.
    • the resource meets all the work skill requirements for this activity, that is, all resource's skill ratios ≥ activity's preferred ratios.
  • The value is 0 if the resource does not have the work skills required for this activity, that is, all resource's skill ratios are less than activity's required ratios.
  • Else, the following formula is used:

    [skill]( resource[skill].ratio - activity[skill].required ) / ( resource[skill].preferable - resource[skill].required )

    with the following exceptions:

    • if dividend ≤ 0, then it is set to 0
    • if divisor is 0, then it is set to 1

Fitness formula for "resourcePreference"

The level of correspondence to activity resource preferences.

  • The value is 0 if:
    • the resource is in the Denied Resources list, or
    • the required Resources list is not empty and the Resource is not in the list
  • The value is 1 if Preferred Resources list is empty or the Resource is in the list.
  • The value is 0.5 for other cases.

From Release 18A onwards, this operation has the ability to search for resources without having to create an activity first. The activity information can be sent in the request using the 'activity' field/property. Some of the important implementation details of the function are as follows:

  • Only one of the parameters (activity, activityId, or activitySearchFields) can be used in each request, if more then one is sent together, then it results in a 400 error.
  • The 'actvityType' value must always be provided in the activity information as it specifies the activity features in OFSC.
  • Depending on the configuration some other activity fields may be required:
    • If Activity type supports work skills, all fields that are used in the work skill conditions are mandatory in the request, and the OFSC configuration is'Activity type Work skill conditions'
    • If Activity type supports work zones, all fields that are part of the work zone key are mandatory in the request, and the OFSC configuration is 'Activity type Work zone key configuration'
    • If the Activity type feature 'Calculate duration' is enabled, then all the fields that are used in the activity duration key are mandatory in the request, and the 'Activity type Statistic parameters - Activity duration key' configuration is used.
    • If the Activity type feature 'Calculate travel' is enabled, then all the fields that are used in the activity travel key are mandatory in the request, and the 'Activity type Statistic parameters - Activity travel key' configuration is used.

Request

Body ()
Root Schema : Find Matching Resources Request
Type: object
Title: Find Matching Resources Request
The schema of the request body object for this operation.
Show Source
  • activity
    The data structure that is used to provide the activity information.
  • Title: Activity ID
    The unique identifier of the activity in Oracle Field Service Cloud. If the Activity ID is specified, then the API uses the properties of the specified activity to find matching resources. Only one of the following parameters can be specified in a same request: 'activity', 'activityId' or 'activitySearchFields'.
  • Activity Search Fields
    Title: Activity Search Fields
    If specified, the API looks for existing activity with matching Appointment Number, Customer Number or both. Then API returns resources to which this activity may be assigned. Only one of the following parameters can be specified in a same request: 'activity', 'activityId' or 'activitySearchFields'.
  • Criteria
    Title: Criteria
    The criteria used to filter the results.

    Results with fitness value greater than the specified cutoff point are removed from response. If a particular criteria is not present, then the API does use the criteria to filter the results. If the criteria parameter is not specified in request, then by default all the criteria is applied.

  • Title: Date
    The date for which the operation calculates the fitness formula. Specify the date in 'YYYY-MM-DD' format.
  • Fields
    Title: Fields
    The array of resource fields that are returned in the response. The specified fields are returned in the response.

    • If the parameter 'fields' is not present, then the default fields 'resourceId', 'status', 'language', and 'languageISO' are returned.
    • If the fields are specified, then the default fields and requested fields are returned.
    • If incorrect fields are specified then, then a 400 error is returned.
    • If the array is empty, then only the default fields are returned.

  • Title: Limit
    The maximum number of resources to be returned in the response. The maximum value that can be specified is 100. If you specify a value greater than 100, it defaults to 100. It is ignored for request with segmentable activity types.
  • Title: Offset
    The number of items to be skipped in the response. It is ignored for request with segmentable activity types.
  • Schedules Fields
    Title: Schedules Fields
    The schedules fields to be returned in the response. The value of this parameter is specified, then only the specified fields are returned in the 'schedules' items for each date. This parameter must be specified along with the 'schedulesToReturn' parameter because the schedules information is returned only if it is specified. It is ignored for request with segmentable activity types.
  • Schedules to Return
    Title: Schedules to Return
    The array of dates for which additional schedules information is returned. It is ignored for request with segmentable activity types.
Nested Schema : activity
The data structure that is used to provide the activity information.
Match All
Show Source
Nested Schema : Activity Search Fields
Type: object
Title: Activity Search Fields
If specified, the API looks for existing activity with matching Appointment Number, Customer Number or both. Then API returns resources to which this activity may be assigned. Only one of the following parameters can be specified in a same request: 'activity', 'activityId' or 'activitySearchFields'.
Show Source
  • Title: Appt Number
    The apptNumber 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 Cloud and can be left empty.
  • 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 Cloud and can be left empty.
Nested Schema : Criteria
Type: object
Title: Criteria
The criteria used to filter the results.

Results with fitness value greater than the specified cutoff point are removed from response. If a particular criteria is not present, then the API does use the criteria to filter the results. If the criteria parameter is not specified in request, then by default all the criteria is applied.

Show Source
  • Title: Include Resources Filter Criteria
    Allowed Values: [ "technicians", "buckets", "all" ]
    The criteria to filter the results by resources. For example, include only technician resource, only bucket resources, or both.
  • Title: Resource Preference Filter Criteria
    Minimum Value: 0
    Maximum Value: 1
    The criteria to filter the results by preference level of the resource.
  • Title: Work Skill Filter Criteria
    Minimum Value: 0
    Maximum Value: 100
    The criteria to filter the results by work skills required to do the activity.
  • Title: Work Time Filter Criteria
    The criteria to filter the results by the time (in minutes) required to complete the activity.
  • Title: Work Zone Filter Criteria
    Minimum Value: 0
    Maximum Value: 100
    The criteria to filter the results by work zone of the activity.
Nested Schema : Fields
Type: array
Title: Fields
The array of resource fields that are returned in the response. The specified fields are returned in the response.

  • If the parameter 'fields' is not present, then the default fields 'resourceId', 'status', 'language', and 'languageISO' are returned.
  • If the fields are specified, then the default fields and requested fields are returned.
  • If incorrect fields are specified then, then a 400 error is returned.
  • If the array is empty, then only the default fields are returned.

Show Source
Nested Schema : Schedules Fields
Type: array
Title: Schedules Fields
The schedules fields to be returned in the response. The value of this parameter is specified, then only the specified fields are returned in the 'schedules' items for each date. This parameter must be specified along with the 'schedulesToReturn' parameter because the schedules information is returned only if it is specified. It is ignored for request with segmentable activity types.
Show Source
  • Title: Schedules Field
    Allowed Values: [ "fitness", "workShift", "freeTimeWindows", "arrivalTimeOptions", "routeDetails" ]
Nested Schema : Schedules to Return
Type: array
Title: Schedules to Return
The array of dates for which additional schedules information is returned. It is ignored for request with segmentable activity types.
Show Source
  • Title: Date
    The date for which the schedules are returned. Specify the date in 'YYYY-MM-DD' format.
Nested Schema : New Activity Properties
Type: object
Title: New Activity Properties
The properties of the new activity.
Show Source
  • Title: Access Schedule
    The schedule (that is, the set of time intervals or access hours, two intervals per week day) when the asset or the activity location is accessible. Work must start and complete during this interval. It is generally not possible to work beyond the access hours.

    Access Schedule Field Format
    This field is a string, which contains an inner json object (encoded as a string). For example, "accessSchedule": "{\"schedule\":[{\"daysOfWeek\":[\"Mon\",\"Tue\"],\"hours\":[[\"07:00\",\"12:00\"]]}]}"

    The inner json object has the following schema:

    {
    "type": "object",
    "properties": {
    "schedule": {
    "type": "array",
    "items": {
    "type": "object",
    "properties": {
    "daysOfWeek": {
    "type": "array",
    "items": {
    "type": "string",
    "enum": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ]
    }
    },
    "hours": {
    "type": "array",
    "items": {
    "type": "array",
    "items": { "type": "string" }
    }
    }
    }
    }
    },
    "exceptDates": {
    "type": "array",
    "items": { "type": "string" }
    }
    }
    }

  • Title: Activity Type

    The type of the activity specified in the request. Based on the activity type, predefined company-specific rules are applied when processing an activity. Predefined company-specific rules cover the following:

    • The resources that the activity can be assigned to.
    • The activity processing details.
    • The interaction of the activity with different modules of Oracle Field Service Cloud.
  • Title: Appt Number
    The apptNumber 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 Cloud and can be left empty.
  • Title: City
    The city of the customer. This field is used for geocoding and must contain a valid address.
  • Title: Country Code
    The code of the country where the activity is scheduled.
  • Title: Customer Cell
    The cell phone number of the customer. The phone number is saved in OFSC 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 OFSC as +12342342342.
  • Title: Customer Email
    The email address of the customer.
  • Title: Customer Name
    The name of the customer.
  • 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 Cloud and can be left empty.
  • Title: Customer Phone
    The regular (land) phone number of the customer. The phone number is saved in OFSC 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 OFSC as +12342342342.
  • Title: Date
    The date on which the activity is scheduled. This field is not present in the response, if the activity is not scheduled for any particular date.
  • Title: Delivery Window End
    The time when the activity delivery window ends. The time is displayed in the time zone of the resource to which the activity is assigned, and is in 'HH:MM:SS' format.
  • Title: Delivery Window Start
    The time when the activity delivery window starts. The time is displayed in the time zone of the resource to which the activity is assigned, and is in 'HH:MM:SS' format.
  • Title: Duration
    Minimum Value: 0
    Maximum Value: 65535
    Estimated activity duration in minutes. The duration specified in request will only be applied if the 'Calculate activity duration using statistics' checkbox is unchecked for the Activity Type of the activity being created/updated. This field is only used for regular activities. To change the length of the multi-day activities please use the field "multidayTimeToComplete" instead.
  • Title: Language
    The preferred language of the customer. It defaults to the language used on the login screen. This parameter accepts the language codes listed on: Supported Language Codes.
  • Title: Latitude
    Minimum Value: -90
    Maximum Value: 90
    The geographic coordinates that specify the location of the activity.
  • Title: Longitude
    Minimum Value: -180
    Maximum Value: 180
    The geographic coordinates that specify the location of the activity.
  • Title: Points
    Minimum Value: 0
    Maximum Value: 65535
    The cost of the activity in 'points'. This field is intended for use by the Routing module.
  • Title: Postal Code
    The postal code of the customer. This field is used for geocoding and must contain a valid address.
  • Title: Reminder Time
    The number of minutes before the activity start time the customer must be notified of the activity.
  • Title: Resource ID

    The identifier of the resource to which this activity is assigned. This field is not returned if the resource ID is empty.

    Note: Do not use empty strings in requests.

  • Title: Service Window End
    The time when the service window ends for the activity. The time is displayed in 'HH:MM:SS' format.

    If the activity type feature 'SLA and Service window use customer time zone' is enabled, then the service window is accepted in the time zone of the customer. If it is not enabled, then the Service Window is accepted in the time zone of the resource to which the activity is currently assigned.

    If the activity is later assigned to another resource and the activity type feature 'SLA and Service window use customer time zone' is enabled, then the Service Window is recalculated so that the fields are not changed in the customer's time zone, but they are changed in the time zone of the new resource.

  • Title: Service Window Start
    The time when the service window starts for the activity. The time is displayed in 'HH:MM:SS' format.

    If the activity type feature 'SLA and Service window use customer time zone' is enabled, then the service window is accepted in the time zone of the customer. If it is not enabled, then the Service Window is accepted in the time zone of the resource to which the activity is currently assigned.

    If the activity is later assigned to another resource and the activity type feature 'SLA and Service window use customer time zone' is enabled, then the Service Window is recalculated so that the fields are not changed in the customer's time zone, but they are changed in the time zone of the new resource.

  • Set Position in Route
    Title: Set Position in Route
    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.
  • Set Travel Time
    Title: Set Travel Time
    The objects used to set the travel time of the activity. The travel time is set only if the specified previousActivity/previousActivityId is ordered before the activity for which the travel time is set.
  • Title: Sla Window End

    The time when the service level agreement (SLA) window ends. The time is displayed in 'YYYY-MM-DD HH:MM:SS' format.

    If the activity type feature 'SLA and Service window use customer time zone' is enabled, then the SLA is accepted in the time zone of the customer. If it is not enabled, then the SLA is accepted in the time zone of the resource to which the activity is currently assigned.

    If the activity is later assigned to another resource and the activity type feature 'SLA and Service window use customer time zone' is enabled, then the SLA is recalculated so that the fields are not changed in the customer's time zone, but they are changed in the time zone of the new resource.

  • Title: Sla Window Start

    The time when the service level agreement (SLA) window starts. The time is displayed in 'YYYY-MM-DD HH:MM:SS' format.

    If the activity type feature 'SLA and Service window use customer time zone' is enabled, then the SLA is accepted in the time zone of the customer. If it is not enabled, then the SLA is accepted in the time zone of the resource to which the activity is currently assigned.

    If the activity is later assigned to another resource and the activity type feature 'SLA and Service window use customer time zone' is enabled, then the SLA is recalculated so that the fields are not changed in the customer's time zone, but they are changed in the time zone of the new resource.

  • Title: State or Province
    The state or province of the customer. This field is used for geocoding and must contain a valid address.
  • Title: Street Address
    The street address of the customer. This field is used for geocoding and must contain a valid address.
  • Title: Team Resource ID
    The identifier of the team resource for a teamwork activity.
  • Title: Time of Booking
    The time when the customer booked the activity. The time is displayed in the time zone of the customer.
  • Title: Time Slot
    The time slot during which the activity is completed. Time Slot also indicates the service window for the activity. This time is displayed in the time zone of the resource to which the activity is assigned.
  • Title: Time Zone

    The name of the customer's time zone. By default, the time zone of the resource (to which the activity is assigned) is used.

    This parameter accepts both OFSC 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. For a list of supported time zones, see Supported Time Zones.

Nested Schema : Set Position in Route
Type: object
Title: Set Position in Route
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 the activity in Oracle Field Service Cloud. If the value of the parameter 'position' is 'afterActivity', then the other activity is scheduled after this activity.
  • Title: Position
    Allowed Values: [ "first", "last", "notOrdered", "byServiceWindow", "afterActivity" ]
    The position of the activity in the route.
Nested Schema : Set Travel Time
Type: object
Title: Set Travel Time
The objects used to set the travel time of the activity. The travel time is set only if the specified previousActivity/previousActivityId is ordered before the activity for which the travel time is set.
Show Source
  • Title: Position
    Allowed Values: [ "first", "afterActivity" ]
    The expected position of the activity in a route.

    To adjust the travel time of an activity, specify the location from where the travel is starting. The location can be the start of the route or another activity. This information is used when activities are reordered or moved while performing a sequence of operations.

  • Previous Activity
    Title: Previous Activity
    The objects in this array are used instead of the 'previousActivityId' parameter to find activities when internal IDs cannot be used. For example, it is used for the bulkUpdate operation.

    The 'previousActivity' activity array contains two items: 'apptNumber' and 'customerNumber'. The parameter 'apptNumber' is mandatory. The parameter 'customerNumber' is only required when the 'bulkUpdate/identifyActivityBy' option is set to 'apptNumberPlusCustomerNumber'.

    The operation returns an error if the system is unable to find any activity using the specified 'apptNumber' and 'customerNumber' values.

  • Title: Previous Activity ID
    The identifier of a previous activity that requires travel time calculation.

    If an activity doesn't require traveling (for example, calling your manager), then the identifier of the activity cannot be used as the 'Travel previous activity ID'. In such case, it is assigned to an ID of a previous activity that required travel.

    This parameter is mandatory when the value of the parameter 'position' is 'afterActivity'.

    Note: The operation does not return any error if the adjustment cannot be made because the specified 'previousActivityId' doesn't correspond to a real-time activity. This can be detected by verifying the 'travelTime' value returned.

  • Title: Source
    Allowed Values: [ "manual", "external" ]
    The origin of the travel time data. The following are the allowed values:
    • manual - indicates that the travel time value is entered manually by a user.
    • external - indicates that the travel time value is estimated based on the statistics or street-level routing service results.
  • Title: Travel Time
    Minimum Value: 0
    Maximum Value: 65535
    The travel time for the specified activity.
Nested Schema : Previous Activity
Type: object
Title: Previous Activity
The objects in this array are used instead of the 'previousActivityId' parameter to find activities when internal IDs cannot be used. For example, it is used for the bulkUpdate operation.

The 'previousActivity' activity array contains two items: 'apptNumber' and 'customerNumber'. The parameter 'apptNumber' is mandatory. The parameter 'customerNumber' is only required when the 'bulkUpdate/identifyActivityBy' option is set to 'apptNumberPlusCustomerNumber'.

The operation returns an error if the system is unable to find any activity using the specified 'apptNumber' and 'customerNumber' values.

Show Source
Back to Top

Response

Supported Media Types

200 Response

This section describes the 200 status response for this operation.
Body ()
Root Schema : Find Matching Resources
Type: object
Title: Find Matching Resources
The list of matching resources.
Show Source
Nested Schema : Resource Matches
Type: array
Title: Resource Matches
The resources matching the criteria specified in the request.
Show Source
  • Resource Match
    Title: Resource Match
    The record of the resource that has matched the specified criteria. For segmentable activity maximum number of items in the response is 25
Nested Schema : Resource Match
Type: object
Title: Resource Match
The record of the resource that has matched the specified criteria. For segmentable activity maximum number of items in the response is 25
Show Source
Nested Schema : Fitness
Type: object
Title: Fitness
The values of the fitness criteria.
Show Source
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
  • Avatar
    Title: Avatar
    The profile picture of the user.

    If an Oracle Field Service Cloud user has a profile picture uploaded (into the 'user.avatar' field) and the specified resource is the user's main resource, then the profile picture can be obtained directly from the resource. This helps to avoid multiple API calls that are otherwise required to find the appropriate user and retrieve the user's profile picture from the 'avatar' field. In order to upload the picture it is necessary to use the "Set a file property" function for appropriate user (using 'avatar' property label).

  • Title: Date Format
    The date format for the resource.
  • Title: Duration Statistics Initial Period
    The number of days the initial ratio is used after a new resource is created. After the specified number of days, the reported duration starts impacting the company estimations. This field is used only if the 'Use durations reported to enhance company-wide estimations' option is selected in the Manage application screen 'Configuration -> Resource Types'. The default value is 5.
  • Title: Duration Statistics Initial Ratio
    The ratio applied over the company estimations if the user hasn't performed any activity. All modifications to the personal profile ratio are done using this value as the starting point. The default value is 1.
  • 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: Language
    The preferred language of the resource. This field accepts the language codes listed on: Supported Language Codes.
  • 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 OFSC 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 OFSC 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 Internal ID
    The unique identifier of the resource in Oracle Field Service Cloud. This is a read-only field.
  • Title: Resource Type
    The type of the resource.
  • Title: Status
    Allowed Values: [ "active", "inactive" ]
    The status of the resource.
  • Title: Time Format
    The time format of the resource.
  • Title: Time Zone
    The name of the resource's time zone. This field accepts both OFSC 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 OFSC 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 Diff
    The difference between UTC and the resource's local time, displayed in minutes. For example, -180 means that the resource time is 3 hours behind UTC.
  • 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 : List of Resource Schedules
Type: object
Title: List of Resource Schedules
Additional Properties Allowed
Show Source
The list of records with the schedule information for each date requested in the schedulesToReturn parameter. Not returned if requested activity is segmentable.
Nested Schema : Avatar
Type: object
Title: Avatar
The profile picture of the user.

If an Oracle Field Service Cloud user has a profile picture uploaded (into the 'user.avatar' field) and the specified resource is the user's main resource, then the profile picture can be obtained directly from the resource. This helps to avoid multiple API calls that are otherwise required to find the appropriate user and retrieve the user's profile picture from the 'avatar' field. In order to upload the picture it is necessary to use the "Set a file property" function for appropriate user (using 'avatar' property label).

Show Source
Nested Schema : Resource Schedule Information
Type: object
Title: Resource Schedule Information
The schedule information of the resource for the specified date.
Show Source
Nested Schema : Arrival Time Options
Type: array
Title: Arrival Time Options
Show Source
Nested Schema : Free Time Windows
Type: array
Title: Free Time Windows
The array of time (in HH:MM format) pairs that specify when the resource is free in a day. For example, [["12:00","14:00"],["15:00","18:00"]].
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 : items
Type: object
Show Source
  • Title: Possible Activity Start To
    The time (in HH:MM format) after which the activity should not start. The activity must not violate any constraints for the particular position in the route.
  • Title: Possible Activity Start From
    The time (in HH:MM format) when the activity can start. It is calculated as the sum of end time of previous activity and travel time to the new activity. The activity must not violate any constraints for the particular position in the route.
  • Set Position in Route
    Title: Set Position in Route
    The data structure used to assign the activity to a particular position in the technician's route. It has the same format as the 'setPositionInRoute' parameter in the 'Create activity' operation.
  • Title: Work Zone Match
    Contains one of the following values: true or false. If true, either the previous or the following activity is in the same work zone as the activity specified in request. If false, then the previous or the following activity are not in the same work zone as the activity specified in request.
Nested Schema : Set Position in Route
Type: object
Title: Set Position in Route
The data structure used to assign the activity to a particular position in the technician's route. It has the same format as the 'setPositionInRoute' parameter in the 'Create activity' operation.
Nested Schema : items
Type: array
Minimum Number of Items: 2
Maximum Number of Items: 2
Show Source
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.

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

Example 1

The following example shows how to find matching resources for segmentable activities by submitting a POST request on the REST resource using cURL.

cURL Command for Example 1

curl -u '<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>' -X POST --url 'https://<instance_name>.etadirect.com/rest/ofscCore/v1/resources/custom-actions/findMatchingResources' --data-binary '{
    "criteria": {
        "resourcePreference":0.0,
        "includeResources":"technicians"
    },
    "date":"2019-09-26",
    "fields": ["resourceId","resourceType"],
    "activity": {
        "duration":500,
        "date":"2019-09-26",
        "activityType":"Multiday",
        "timeZone":"America/New_York",
        "city":"ALTAMONTE SPRINGS"
    }
}'

Response Body for Example 1

{
    "items": [
        {
            "resource": {
                "resourceId": "Aslan_Atees",
                "status": "active",
                "resourceType": "PR",
                "language": "en",
                "languageISO": "en-US"
            },
            "fitness": {
                "workTime": 0,
                "workZone": 100,
                "workSkill": 100,
                "resourcePreference": 1
            },
            "estimatedCompleteDate": "2019-09-27"
        },
        {
            "resource": {
                "resourceId": "Ayisha_Bolukbasi",
                "status": "active",
                "resourceType": "PR",
                "language": "en",
                "languageISO": "en-US"
            },
            "fitness": {
                "workTime": 0,
                "workZone": 100,
                "workSkill": 100,
                "resourcePreference": 1
            },
            "estimatedCompleteDate": "2019-09-27"
        }
    ]
}

Example 2

The following example shows how to find matching resources without having to create an activity first, by submitting a POST request on the REST resource.

Request for Example 2

POST https://<instance_name>.etadirect.com/rest/ofscCore/v1/resources/custom-actions/findMatchingResources

{
    "criteria": {
        "resourcePreference": 0.0,
        "workSkill": 100,
        "workTime": 100,
        "workZone": 100,
        "includeResources": "technicians"
    },
    "limit": 3,
    "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"
    }
}

Response for Example 2

{
    "totalResults": 5884,
    "limit": 3,
    "offset": 0,
    "items": [
        {
            "resource": {
                "resourceId": "test_change_password",
                "status": "active",
                "parentResourceId": "change_password_login_policy",
                "resourceType": "provider_team_holder_share_full",
                "language": "en",
                "languageISO": "en-US"
            },
            "fitness": {
                "workTime": 1435,
                "workZone": 100,
                "workSkill": 100,
                "resourcePreference": 1
            },
            "schedules": {
                "2018-01-16": {
                    "fitness": {
                        "workTime": 1435,
                        "workSkill": 100,
                        "workZone": 100,
                        "resourcePreference": 1
                    },
                    "workShift": {
                        "comments": "Regular",
                        "endDate": "",
                        "startDate": "2013-12-30",
                        "isWorking": "1",
                        "nonWorkingReason": "",
                        "points": "0",
                        "recordType": "working",
                        "recurrence": {
                            "dayFrom": "",
                            "dayTo": "",
                            "recurEvery": "1",
                            "recurrenceType": "weekly",
                            "weekdays": [
                                "Mon",
                                "Tue",
                                "Wed",
                                "Thu",
                                "Fri"
                            ]
                        },
                        "workTimeEnd": "23:55",
                        "workTimeStart": "00:00",
                        "shiftType": "",
                        "shiftLabel": "",
                        "scheduleShifts": []
                    },
                    "freeTimeWindows": []
                }
            }
        },
     ...
    "links": [
        {
            "rel": "next",
            "href": "http://localhost/rest/ofscCore/v1/resources/custom-action/findMatchingResources/?limit=3&offset=3"
        }
    ]
}
Back to Top