Find matching resources

post

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

Use this operation to retrieve the list of resources that are used to complete this activity according to the request criteria. Only the resources that match the criteria specified in the request will be returned.

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 Activity type feature 'Calculate duration' is on, all fields that are used in the activity duration key are mandatory in the request, and the OFSC configuration is 'Activity type Statistic parameters - Activity duration key'
    • If Activity type feature 'Calculate travel' is on, all fields that are used in the activity travel key are mandatory in the request, and the OFS configuration is 'Activity type Statistic parameters - Activity travel key'

Request

Body ()
Root Schema : Find matching resources request
Type: object
Title: Find matching resources request
Resources that match the criteria specified in this request will be returned.
Show Source
  • activity
    The data structure used to provide information about the activity.
  • Title: Activity ID
    If a value is specified, the API uses properties of an existing activity to find matching resources. Either Activity ID or Activity Search Fields must be specified in the request.
  • Activity Search Fields
    Title: Activity Search Fields
    If a value is specified, the API looks for existing acitivity with matcing Appoitment Number, Customer Number, or both. Then the API returns the resources to which this activity may be assigned.
  • Criteria
    Title: Criteria
    The API uses this criteria to filter results. Results with the fitness value greater than the specified cutoff point are removed from the response. If a particular criteria is missing, the API does not filter the results using the criteria. When this parameter is not set in request, by default all the criteria is applied.
  • Title: Date
    The API calculates the fitness of the activity for this date. Specify the date in "YYYY-MM-DD" format.
  • Fields
    Title: Fields

    An array of resource fields to be returned in the response.

    • If the parameter "fields" is missing, only the fields "resourceId", "status", "language" and "languageISO" are returned in the response.
    • When you specify the fields, only the default fields and the requested fields are returned.
    • If you specify incorrect fields, 400 error is returned.
    • If the list is empty, only default fields are returned.

  • Title: Limit
    The number of items to be returned. You can specify upto 100 items.

    Note: If you specify the limit greater than 100, it will be set to 100.

  • Title: Offset
    The number of items to be skipped.
  • Schedules Fields
    Title: Schedules Fields

    If the fields are specified in this parameter, then only these fields/subobjects will be returned in the "schedules" items for each date. Specify this parameter along with the "schedulesToReturn" parameter, as the schedules are returned according to the schedules specified in the "schedulesToReturn" parameter. The default values are "fitness", "workShift", "freeTimeWindows".

  • Schedules To Return
    Title: Schedules To Return
    The API returns additional information about the schedule for this array of dates.
Nested Schema : activity
The data structure used to provide information about the activity.
Match All
Show Source
Nested Schema : Activity Search Fields
Type: object
Title: Activity Search Fields
If a value is specified, the API looks for existing acitivity with matcing Appoitment Number, Customer Number, or both. Then the API returns the resources to which this activity may be assigned.
Show Source
Nested Schema : Criteria
Type: object
Title: Criteria
The API uses this criteria to filter results. Results with the fitness value greater than the specified cutoff point are removed from the response. If a particular criteria is missing, the API does not filter the results using the criteria. When this parameter is not set in request, by default all the criteria is applied.
Show Source
  • Title: Include Resources Filter Criteria
    Allowed Values: [ "technicians", "buckets", "all" ]
    Specify this criteria to retrieved only technician resources, only bucket resources, or both.
  • Title: Resource Preference Filter Criteria
    Minimum Value: 0
    Maximum Value: 1
    Specify this criteria to retrieve only the resources that meet the specified resource preference level.
  • Title: Work Skill Filter Criteria
    Minimum Value: 0
    Maximum Value: 100
    Specify this criteria to retrieve only the resources that have work skills required to perform the activity.
  • Title: Work Time Filter Criteria
    Specify this criteria to retrieve only the resources that have at least the specified amount of work time (in minutes) to perform the activity.
  • Title: Work Zone Filter Criteria
    Minimum Value: 0
    Maximum Value: 100
    Specify this criteria to retrieve only the resources that work at the work zone that belongs to the activity.
Nested Schema : Fields
Type: array
Title: Fields

An array of resource fields to be returned in the response.

  • If the parameter "fields" is missing, only the fields "resourceId", "status", "language" and "languageISO" are returned in the response.
  • When you specify the fields, only the default fields and the requested fields are returned.
  • If you specify incorrect fields, 400 error is returned.
  • If the list is empty, only default fields are returned.

Show Source
Nested Schema : Schedules Fields
Type: array
Title: Schedules Fields

If the fields are specified in this parameter, then only these fields/subobjects will be returned in the "schedules" items for each date. Specify this parameter along with the "schedulesToReturn" parameter, as the schedules are returned according to the schedules specified in the "schedulesToReturn" parameter. The default values are "fitness", "workShift", "freeTimeWindows".

Show Source
  • Title: Schedules Field
    Allowed Values: [ "fitness", "workShift", "freeTimeWindows", "arrivalTimeOptions", "routeDetails" ]
Nested Schema : Schedules To Return
Type: array
Title: Schedules To Return
The API returns additional information about the schedule for this array of dates.
Show Source
Nested Schema : New activity properties
Type: object
Title: New activity properties
An object containing the properties of the new activity.
Show Source
  • Title: Access Schedule
    Access Schedule defines the schedule (i.e. the set of time intervals/access hours, two intervals per week day) when the asset or the activity location is accessible. Work should be started and finished during the same Access Schedule interval. Performing the work beyond Access Hours is generally not possible.

    Access Schedule field format
    This field is a string, which contains an inner json object (encoded as a string). e.g. "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
    A predefined company-specific set of rules applied to process an activity. These rules include the resources the activity can be assigned to, details of the processing, and interaction with different modules of Oracle Field Service Cloud.
  • Title: Appt Number
    This field is used by integrations to hold the external Id of the activity in the origin system. It has no business logic in Oracle Field Service Cloud and can be left empty.
  • Title: City

    The customer's address

    Note: this field is used by geocoding and, therefore, must contain a valid address. Other values will not be resolved correctly by the geocoding server.

  • Title: Country code
    The country code
  • Title: Customer Cell
    The customer's cell phone number. From version 17.2.1, the phone number is saved in OFSC with the '+' symbol. For example, if you enter the phone number as +1(234)234-23_42, it is saved in OFSC as +12342342342. In versions before 17.2.1, the phone number is saved 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 to hold the external Id of the Account ID in the origin system. It has no business logic in Oracle Field Service Cloud and can be left empty.
  • Title: Customer Phone
    The customer's regular (land) phone number. From version 17.2.1, the phone number is saved in OFSC with the '+' symbol. For example, if you enter the phone number as +1(234)234-23_42, it is saved in OFSC as +12342342342. In versions before 17.2.1, the phone number is saved as 12342342342.
  • Title: Date
    The date when this activity is scheduled. This field will not be available if the activity is not scheduled for any particular date.
  • Title: Delivery Window End
    The end time of the activity delivery window. Specify the time in HH:MM:SS format.
  • Title: Delivery Window Start
    The start time of the activity delivery window. Specify the time in HH:MM:SS format.
  • Title: Duration
    Minimum Value: 0
    Maximum Value: 65535
    The estimated duration of the activity 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.
  • Title: Language
    The customer's preferred language

    This field is optional, and defaults to the language that is set for the Login screen. The following language codes are accepted: Supported Language Codes.

  • Title: Latitude
    Minimum Value: -90
    Maximum Value: 90
    The coordinates for the activity.
  • Title: Longitude
    Minimum Value: -180
    Maximum Value: 180
    The coordinates for 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 customer's postal code.

    Note: this field is used by geocoding and, therefore, must contain a valid address. Other values will not be resolved correctly by the geocoding server.

  • Title: Reminder Time
    The time when the reminder notification is scheduled. Specify the number of minutes before the activity start time the customer should be notified.
  • Title: Resource Id
    The unique identifier of the resource this activity is assigned to. This field is not displayed if the resourceId is an empty string. Empty strings should not be used in the request.
  • Title: Service Window End

    The end time of the Service window. Specify the time in "HH:MM:SS" format.

    If the activity type is configured with the parameter 'SLA and Service window use customer time zone' then Service Window is accepted in the time zone of customer (field 'timeZone'), otherwise Service Window is accepted in the time zone of the resource to which this activity is assigned.

    Note: If the activity is moved to another resource, and has the activity type feature 'SLA and Service window use customer time zone' enabled, then Service Window will be recalculated, so that these fields remain unchanged in the customer's time zone, but appear to be changed in the time zone of the new resource.

  • Title: Service Window Start

    The start time of the Service window. Specify the time in "HH:MM:SS" format.

    If the activity type is configured with the parameter 'SLA and Service window use customer time zone' then the Service window is accepted in the time zone of customer (field 'timeZone'), otherwise the Service window is accepted in the time zone of the resource to which this activity is assigned.

    Note: If the activity is moved to another resource, and has the activity type feature 'SLA and Service window use customer time zone' enabled, then the Service window will be recalculated, so that these fields remain unchanged in the customer's time zone, but appear to be changed in the time zone of the new resource.

  • Set Position in Route
    Title: Set Position in Route
    If this field is available then the activity will be set to the specified position in the route.
  • Set travel time
    Title: Set travel time
    If this field is available then the application will attempt to set the travel time of the activity. The travel time will only be set if the specified previousActivity/previousActivityId is ordered before the activity you are setting the travel time for.
  • Title: Sla Window End

    The end time of the SLA window. Specify the date and time in "YYYY-MM-DD HH:MM:SS" format.

    If the activity type is configured with the parameter 'SLA and Service window use customer time zone' then SLA is accepted in the time zone of customer (field 'timeZone'), otherwise SLA is accepted in the time zone of the resource to which this activity is assigned.

    Note: If the activity is moved to another resource, and has the activity type feature 'SLA and Service window use customer time zone' enabled, then SLA will be recalculated so that these fields remain unchanged in the customer's time zone, but appear to be changed in the time zone of the new resource.

  • Title: Sla Window Start

    The start time of the SLA window. Specify the date and time in "YYYY-MM-DD HH:MM:SS" format.

    If the activity type is configured with the parameter 'SLA and Service window use customer time zone' then SLA is accepted in the time zone of customer (field 'timeZone'), otherwise SLA is accepted in the time zone of the resource to which this activity is assigned.

    Note: If the activity is moved to another resource, and has the activity type feature 'SLA and Service window use customer time zone' enabled, then SLA will be recalculated so that these fields remain unchanged in the customer's time zone, but appear to be changed in the time zone of the new resource.

  • Title: State Province

    The state/province of the customer.

    Note: This field is used by geocoding and, therefore, must contain a valid address. Other values will not be resolved correctly by the geocoding server.

  • Title: Street Address

    The customer's address.

    Note: This field is used by geocoding and, therefore, must contain a valid address. Other values will not be resolved correctly by the geocoding server.

  • Title: Team Resource ID
    The identifier of the team resource if this activity is a team work.
  • Title: Time Delivered End
    The end time of the arrival interval as coomunicated to the customer.
  • Title: Time Delivered Start
    The start time of the arrival interval as coomunicated to the customer.
  • Title: Time of Assignment
    The time of the activity assignment.
  • Title: Time of Booking
    The time of the booking assignment.
  • Title: Time Slot
    The time slot of the Activity. It defines the service window.
  • Title: Time Zone

    The name of the customer's time zone.

    Note: This field accepts both OFSC time zone names (e.g. "Eastern") and IANA standard zone names (e.g. "America/New_York"). It is recommended that IANA names are used.

    This field is optional, and defaults to the time zone of the resource the activity is created on. For a list of supported time zones, see Supported Time Zones.

Nested Schema : Set Position in Route
Type: object
Title: Set Position in Route
If this field is available then the activity will be set to the specified position in the route.
Show Source
  • Title: Activity ID
    If the value of "position" is "afterActivity" then the new activity will be positioned after this activityId.
  • 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
If this field is available then the application will attempt to set the travel time of the activity. The travel time will only be set if the specified previousActivity/previousActivityId is ordered before the activity you are setting the travel time for.
Show Source
  • Title: Position
    Allowed Values: [ "first", "afterActivity" ]
    The expected position of the activity in a route.

    In order to adjust the travel time for an activity, it is necessary to specify the start location for the travel. This location can be the start of the route or another activity.

    This information is mainly used to handle situations when activities are reordered or moved during performing a sequence of operations.

  • Previous Activity
    Title: Previous Activity

    This field can be used instead of 'previousActivityId' for commands that do not use internal IDs. For example, you can use this field for the 'bulkUpdate' command which doesn't use internal IDs.

    The 'previousActivity' array contains two items: 'apptNumber' and 'customerNumber'. It is mandatory to specify a value for 'apptNumber'. 'CustomerNumber' is only required when the 'bulkUpdate/identifyActivityBy' option is set to 'apptNumberPlusCustomerNumber'.

    Note: This function returns an error when the system is unable to find any activity using the values specified for 'apptNumber' and 'customerNumber'.

  • Title: Previous Activity ID

    The unique identifier of the previous activity that requires calculation of travel time. If there is an activity that doesn't require traveling (for example: Call to manager), the identifier of this activity cannot be not used as 'Travel previous activity ID'. In this case, it is assigned to an ID of a previous activity that requires traveling.

    This field is mandatory when the 'position' is set to 'afterActivity'.

    Note: The function doesn't return an error when the adjustment cannot be performed because the specified 'previousActivityId' doesn't correspond to an actual situation. This situation can be detected by checking a returned 'travelTime' value.

  • Title: Source
    Allowed Values: [ "manual", "external" ]

    The source of the travel time data.

    The value 'manual' indicates that the adjustment value is entered by a human.The value '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

This field can be used instead of 'previousActivityId' for commands that do not use internal IDs. For example, you can use this field for the 'bulkUpdate' command which doesn't use internal IDs.

The 'previousActivity' array contains two items: 'apptNumber' and 'customerNumber'. It is mandatory to specify a value for 'apptNumber'. 'CustomerNumber' is only required when the 'bulkUpdate/identifyActivityBy' option is set to 'apptNumberPlusCustomerNumber'.

Note: This function returns an error when the system is unable to find any activity using the values specified for 'apptNumber' and 'customerNumber'.

Show Source
Back to Top

Response

Supported Media Types

200 Response

Body ()
Root Schema : Find Matching Resources Response
Type: object
Title: Find Matching Resources Response
The list of matching resources
Show Source
Nested Schema : Resource Matches
Type: array
Title: Resource Matches
An array of items containing the resources matching the request criteria.
Show Source
Nested Schema : Resource Match
Type: object
Title: Resource Match
An array of objects containing the resource match records.
Show Source
Nested Schema : Fitness
Type: object
Title: Fitness
The criteria for Fitness.
Show Source
Nested Schema : Resource
Type: object
Title: Resource
Resource (which can represent e.g. a technician, a truck, a bucket). Not to confuse with REST resource.
Show Source
  • Avatar
    Title: Avatar
    User profile picture. If an Oracle Field Service Cloud user has an 'avatar' picture uploaded and this resource is specified as a 'main resource' for that user, then the avatar picture can be obtained directly from the resource. This is to avoid multiple API calls that would otherwise be needed to retrieve the user profile picture.
  • Title: Date Format
    Date Format
  • Title: Duration statistics initial period
    Number of days the initial ratio will be used after a new resource is created. After this number of days passes, the reported duration will start impacting company estimations. This will be used only if 'Use durations reported to enhance company-wide estimations' is checked in Manage application screen 'Configuration -> Resource Types'. Default: 5.
  • Title: Duration statistics initial ratio
    The ratio to be applied over company estimations if the user hasn't performed any activity before. All modifications to personal profile ratio will be done with this value as the starting point. Default: 1
  • Title: Email
    Email ID of the resource. This field has a maximum length of 255 characters. If you provide a longer value in the request, only the first 255 characters will be saved and the rest will be ignored.
  • Title: Language
    Language. When setting this field, the following language codes are accepted: Supported Language Codes.
  • Title: Name
    Minimum Length: 1
    Name of the resource. This field has a maximum length of 40 characters. If you provide a longer value in the request, only the first 40 characters will be saved and the rest will be ignored.
  • Title: Parent Resource Id
    Parent Resource Id
  • Title: Phone

    The phone number of the resource. This field has a maximum length of 16 characters. If you provide a longer value in the request, only the first 16 characters will be saved and the rest will be ignored.

    Note: From version 17.2.1, the phone number is saved in OFSC with the '+' symbol. For example, if you enter the phone number as +1(234)234-23_42, it is saved in OFSC as +12342342342. In versions before 17.2.1, the phone number is saved as 12342342342.

  • Title: Resource Id
    Resource ID in external system. This field has a maximum length of 32 characters. If you provide a longer value in the request, the request will fail with HTTP 400 error.
  • Title: Resource Internal Id
    Resource Id in Field Service Cloud. This field is read-only.
  • Title: Resource Type
    Resource Type
  • Title: Status
    Allowed Values: [ "active", "inactive" ]
    Status
  • Title: Time Format
    Time Format
  • Title: Time Zone
    Resources's time zone name.

    Note that this field accepts both OFSC time zone names (e.g. "Eastern") and IANA standard zone names (e.g. "America/New_York"). It is recommended that IANA names are passed. When returned in response, this field will contain OFSC name, while another field "timeZoneIANA" will contain IANA name.

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

  • Title: Time Zone Diff
    Time Zone Diff
  • Title: Time Zone IANA name
    IANA name of the time zone. (https://www.iana.org/time-zones). Example: "America/New_York".

    Note this field is read-only - is only returned in responses.

Nested Schema : Schedule
Type: object
Title: Schedule
Additional Properties Allowed
Show Source
The schedule information of a resource or each date requested in schedulesToReturn request parameter.
Nested Schema : Avatar
Type: object
Title: Avatar
User profile picture. If an Oracle Field Service Cloud user has an 'avatar' picture uploaded and this resource is specified as a 'main resource' for that user, then the avatar picture can be obtained directly from the resource. This is to avoid multiple API calls that would otherwise be needed to retrieve the user profile picture.
Show Source
Nested Schema : Resource Schedule Info
Type: object
Title: Resource Schedule Info
An object containing the schedule information of a 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
An array of time (HH:MM) pairs that specify if the resource has free time this 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
An array containing resource work schedule items.
Show Source
  • Title: Comments
    The description of this work schedule in the OFSC application.
  • Title: End Date
    The date when this schedule ends. The format is "YYYY-MM-DD".
  • Title: Is Working Shift
    This is a read-only field calculated based on the record type or the shift settings.
    • If the value is true, then it is a working day.
    • If the value is false, then it is a non-working day.
  • Title: Non-working Reason
    The reason for this day to be a a non-working day (for example, holiday, vacation). These reasons are preconfigured in the OFSC UI.
  • Title: Points
    "Units of labor per day" for the days this work 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 this work schedule.
  • Recurrence
    Title: Recurrence
    An array containing recurring work schedule items.
  • Title: Work Schedule Item ID
    A unique internal identifier of this work schedule item. This ID is used to delete the item.
  • Title: Work Schedule Label
    The label of this work schedule on OFSC UI. This property is only available if recordType= "schedule".
  • Shifts
    Title: Shifts
    The list of shifts available in this work schedule. The shift properties are for information purpose only and cannot be modified using this API.
  • Title: Work Shift Label
    The lable of the work shifts on OFSC UI. This property is only available if recordType is either shift or extra_shift.
  • Title: Shift Type
    Allowed Values: [ "regular", "on-call" ]
    The type of this 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 a working day when this schedule is in effect. The format is "HH:MM". This property is not available when isWorking = "false".
  • Title: Work Time Start
    The start time of a working day when this schedule is in effect. The format is "HH:MM". This property is not available when isWorking = "false".
Nested Schema : items
Type: object
Show Source
  • Title: Possible Activity startTo
    The new activity should start no later than this time so that it does not violate any constraints in the route for the particular position. The time is specified in "HH:MM" format.
  • Title: Possible Activity startFrom
    The new activity can start no earlier than this time so that it does not violate any constraints in the route for the particular position. The time is specified in "HH:MM" format. This time is calculated as follows: end time of previous activity + travel time to the new activity.
  • Set Position In Route
    Title: Set Position In Route
    Use this data structure 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' endpoint.
  • Title: Work Zone Match
    Indicates if at least one of the activities (previous or following) has the same work zone as the activity specified in the request. The value is 'true' if either the previous or the following activity is in the same work zone.
Nested Schema : Set Position In Route
Type: object
Title: Set Position In Route
Use this data structure 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' endpoint.
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.
Show Source
  • Title: Day From
    The start day (in "YYYY-MM-DD") of the schedule period, each year, when the schedule is in effect. It is only used for recurrenceType="yearly".
  • Title: Day To
    The end day (in "YYYY-MM-DD") of the schedule period, each year, when the schedule is in effect. It is only used for recurrenceType="yearly".
  • Title: Recur Every
    Minimum Value: 1
    Maximum Value: 255
    The time between each recurrence of the event. Depending on the value selected for "recurrenceType", this property value indicates the time between recurrence in days, weeks, or years. For example, if "4" is the value for this property, and the "recurrenceType" is "daily", it indicates that the time between each recurrence is four days.
  • Title: Recurrence Type
    Allowed Values: [ "daily", "weekly", "yearly", "everyday" ]
    This property along with the "recurEvery" property defines the time between each recurrence. For example, if you select "daily" for this property and "4" as the value for "recurEvery", the time between each recurrence will be four days.
  • Recurrence Weekdays
    Title: Recurrence Weekdays
    An array containing recurrence weekdays.
Nested Schema : Shifts
Type: array
Title: Shifts
The list of shifts available in this work schedule. The shift properties are for information purpose only and cannot be modified using this API.
Show Source
Nested Schema : Recurrence Weekdays
Type: array
Title: Recurrence Weekdays
An array containing recurrence weekdays.
Show Source
  • Title: Weekday
    Allowed Values: [ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ]
    A day of the week. Required only if recurrenceType="weekly".
Nested Schema : Resource Shift Item
Type: object
Title: Resource Shift Item
An object containing resource shift items.
Show Source
Nested Schema : Recurrence
Type: object
Title: Recurrence
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") of this shift, each year, when the shift is in effect. It is only used for recurrenceType="yearly".
  • Title: Day To
    The end day (in "YYYY-MM-DD") of this shift, each year, when the shift is in effect. It is only used for recurrenceType="yearly".
  • Title: Recur Every
    Minimum Value: 1
    Maximum Value: 255
    The time between each recurrence of the event. Depending on the value selected for "recurrenceType", this property value indicates the time between recurrence in days, weeks, or years. For example, if "4" is the value for this property, and the "recurrenceType" is "daily", it indicates that the time between each recurrence is four days.
  • Title: Recurrence Type
    Allowed Values: [ "daily", "weekly", "yearly", "everyday" ]
    This property along with the "recurEvery" property defines the time between each recurrence. For example, if you select "daily" as the value of this property and "4" as the value for "recurEvery", the time between each recurrence will be four days.
  • Recurrence Weekdays
    Title: Recurrence Weekdays
    An array containing the recurrence weekdays
Nested Schema : Recurrence Weekdays
Type: array
Title: Recurrence Weekdays
An array containing the recurrence weekdays
Show Source
  • Title: Weekday
    Allowed Values: [ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ]
    The day of the week. Required only if recurrenceType="weekly".

Default Response

Error response
Body ()
Root Schema : Error
Type: object
Show Source
Back to Top

Examples

Example 1

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

cURL Command for Example 1

curl -u '***' -X POST --url 'https://api.etadirect.com/rest/ofscCore/v1/resources/custom-actions/findMatchingResources' --data-binary '{
      "date" : "2018-04-07",
      "activity": {
        "activityType": "33",
        "duration": 30,
        "serviceWindowStart": "13:00:00",
        "serviceWindowEnd"  : "15:00:00",
        "streetAddress": "12345 Stuyvesant Ave",
        "city" : "ALTAMONTE SPRINGS",
        "timeZone" : "America/New_York"
      },
      "criteria": {
        "workTime":0,
        "workZone":0,
        "workSkill":0,
        "resourcePreference":0
      },
      "fields" : ["name", "resourceInternalId"],
      "schedulesToReturn": ["2018-04-07"],
      "schedulesFields" : ["arrivalTimeOptions"],
      "limit" : 2
}'

Response Body for Example 1

{
    "totalResults": 1522,
    "limit": 2,
    "offset": 0,
    "items": [
        {
            "resource": {
                "resourceId": "11106",
                "resourceInternalId": 1100006,
                "status": "active",
                "name": "(fast TC) BAPTIST, Roger",
                "language": "en",
                "languageISO": "en-US"
            },
            "fitness": {
                "workTime": 120,
                "workZone": 0,
                "workSkill": 100,
                "resourcePreference": 1
            },
            "schedules": {
                "2018-04-07": {
                    "arrivalTimeOptions": [
                        {
                            "minStartTime": "13:00",
                            "maxStartTime": "15:00",
                            "workZoneMatch": false,
                            "setPositionInRoute": {
                                "position": "first"
                            }
                        }
                    ]
                }
            }
        },
        {
            "resource": {
                "resourceId": "11107",
                "resourceInternalId": 1100007,
                "status": "active",
                "name": "(fast TC) CLAIR, Jesse",
                "language": "en",
                "languageISO": "en-US"
            },
            "fitness": {
                "workTime": 120,
                "workZone": 0,
                "workSkill": 100,
                "resourcePreference": 1
            },
            "schedules": {
                "2018-04-07": {
                    "arrivalTimeOptions": [
                        {
                            "minStartTime": "13:00",
                            "maxStartTime": "14:04",
                            "workZoneMatch": true,
                            "setPositionInRoute": {
                                "position": "afterActivity",
                                "activityId": 4225405
                            }
                        },
                        {
                            "minStartTime": "13:56",
                            "maxStartTime": "15:00",
                            "workZoneMatch": true,
                            "setPositionInRoute": {
                                "position": "afterActivity",
                                "activityId": 4225406
                            }
                        }
                    ]
                }
            }
        }
    ],
    "links": [
        {
            "rel": "next",
            "href": "https://api.etadirect.com/rest/ofscCore/v1/resources/custom-action/findMatchingResources/?limit=2&offset=2"
        }
    ]
}

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://api.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