Find resources for urgent assignment

post

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

This operation retrieves a list of resources that can immediately perform an activity based on the criteria specified in the request.

Only the resources matching the specified criteria are returned in the response.

Request

Body ()
Root Schema : Find Matching Resources for Urgent Assignment Request
Type: object
Title: Find Matching Resources for Urgent Assignment Request
The schema of the request body object for this operation.
Show Source
  • activity
    The properties of the activity. This is a required parameter.
  • Parent Resource ID
    Title: Parent Resource ID
    The list of identifiers of the parent resources.

    If this parameter is specified, then the operation evaluates only the children of the specified resources and their descendants. If this parameter is not specified, then all resources are evaluated and returned in the response.

  • Title: Radius
    Minimum Value: 0
    Maximum Value: 300000
    The radius of area (in meters) where the search is performed.

    If the value is not specified in the request, then it defaults to 100000 meters.

  • Resource Fields
    Title: Resource Fields
    The resource fields to be returned in the response.

    If this parameter is not specified in the request, then the default resource fields, 'resourceId', 'resourceInternalId', 'name', 'resourceType' are returned.

    Using this parameter, it is possible to specify the list of fields that are needed for the integration flow to increase the performance and reduce the traffic.

    When the resource fields are specified, only the 'resourceId' field and the requested fields are returned.

    If incorrect resource fields are specified, then the 400 error code is returned.

Nested Schema : activity
The properties of the activity. This is a required parameter.
Match All
Show Source
Nested Schema : Parent Resource ID
Type: array
Title: Parent Resource ID
The list of identifiers of the parent resources.

If this parameter is specified, then the operation evaluates only the children of the specified resources and their descendants. If this parameter is not specified, then all resources are evaluated and returned in the response.

Show Source
Nested Schema : Resource Fields
Type: array
Title: Resource Fields
The resource fields to be returned in the response.

If this parameter is not specified in the request, then the default resource fields, 'resourceId', 'resourceInternalId', 'name', 'resourceType' are returned.

Using this parameter, it is possible to specify the list of fields that are needed for the integration flow to increase the performance and reduce the traffic.

When the resource fields are specified, only the 'resourceId' field and the requested fields are returned.

If incorrect resource fields are specified, then the 400 error code is returned.

Show Source
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 for Urgent Assignment
Type: object
Title: Find Matching Resources for Urgent Assignment
The list of resources that match the criteria for urgent assignment.
Show Source
Nested Schema : Resource Matches for Urgent Assignment
Type: array
Title: Resource Matches for Urgent Assignment
The resources that match the specified request criteria for urgent assignment.
Show Source
Nested Schema : Resource Match
Type: object
Title: Resource Match
The record of the resource that has matched the specified criteria.
Show Source
Nested Schema : resourceDetails
Type: object
The data structure that contains the resource information.
Show Source
Match All
Show Source
Nested Schema : resourceDetails
Type: object
Show Source

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

The following example shows how to find resources for urgent activity assignments by submitting a POST request on the REST resource:

cURL Command Example

curl -u "<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>" \
    -X POST \
    --data-binary '{
        "activity": {
        "latitude": 28.6685,
        "longitude": -81.4181,
        "activityType": "urgent-outage",
        "language": "en-US",
        "timeZone": "America/New_York",
        "city": "Altamonte Springs",
        "postalCode": "12345"
    },
    "radius": 300000,
    "resourceFields": [
        "resourceId",
        "name"
    ],
    "parentResources": [
        "east-x02"
    ]
        }' \
'https://<instance_name>.etadirect.com/rest/ofscCore/v1/resources/custom-actions/findResourcesForUrgentAssignment'

Response Header Example

The following shows an example of the response header.

HTTP/1.1 200 OK
Server: nginx/1.6.3
Date: Wed, 16 Sep 2015 15:32:19 GMT
Content-Type: application/json; charset=utf-8
Connection: close
X-Powered-By: PHP/7.0.25

Response Body Example

The following shows an example of the response body in JSON format.

{
    "items": [
        {
            "longitude": 28.66,
            "latitude": -81.41,
            "nearestRoutingBucket": "ResourcesGVHYFDBDGP1",
            "startTime": "2018-01-31 14:10:00",
            "estimatedAvailability": "2018-01-31 14:40:00",
            "resourceDetails": {
                "resourceId": "rx0101",
                "name": "Jane Doe"
            }
        },
        {
            "longitude": 28.67,
            "latitude": -81.40,
            "nearestRoutingBucket": "ResourcesGVHYFDBDGP2",
            "startTime": "2018-01-31 14:20:33",
            "estimatedAvailability": "2018-01-31 14:50:00",
            "resourceDetails": {
                "resourceId": "rx0202",
                "name": "Jack Smith"
            }
        }
    ]
}
Back to Top