Get a resource route

get

/rest/ofscCore/v1/resources/{resourceId}/routes/{date}

This operation retrieves a list of activities assigned to the specified resource for the specified date.

Special values can be specified in the date field to return a list of activities not scheduled for a specific date or to return a list of segmentable activities assigned to the resource.

Request

Supported Media Types
Path Parameters
  • The date of the route. The date can have the following values:
    • The date in YYYY-MM-DD format.
    • Special value 'nonScheduled' to return activities without a specific date.
    • Special value 'multiday' to return segmentable activities.
    • The unique identifier of the resource.
    Query Parameters
    • Collection Format: csv
      The comma-separated names of the activity fields (properties) returned in the response. The available fields are same as those present in the 'get activity' method except for the file properties. The start time and time zone information is returned when the parameter is ignored.
    • The number of items to be returned in the response. The minimum value that can be specified is 1 and the maximum value that can be specified is 100. If the specified value is greater than 100, zero, or if no value is specified, then it defaults to 100.
    • The record number from which the retrieval starts. The default value is zero. If no value is specified, then it defaults to zero. The value zero indicates that the retrieval will start from the beginning of the collection.
    Back to Top

    Response

    Supported Media Types

    200 Response

    This section describes the 200 status response for this operation.
    Body ()
    Root Schema : Route
    Type: object
    Title: Route
    The route of the specified resource.
    Show Source
    Nested Schema : Items
    Type: array
    Title: Items
    The list of activity fields.
    Show Source
    Nested Schema : Activity Properties
    Type: object
    Title: Activity Properties
    The array of activity property objects.
    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 ID
      The unique identifier of the activity.
    • Title: Activity Type
      The type of the activity specified in the request. Based on the activity type, predefined company-specific rules are applied while processing an activity. Predefined company-specific rules cover the following:
      • The resources to which the activity is assigned.
      • The activity processing details.
      • The interaction of the activity with different modules of Oracle Field Service Cloud.
    • Title: Appointment Number
      This field may be used by integrations to store the identifier of the activity in the origin system. This field has no business significance in Oracle Field Service Cloud and can be left empty.
    • Title: City
      The city of the customer where the activity is scheduled.
    • Title: Country Code
      The code of the country where the activity is scheduled.
    • Title: Customer Cell
      The cell phone number of the customer. From version 17.2.1, the phone number is saved with the '+' symbol. For example, if you enter the phone number as +1(234)234-23_42, it is saved 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 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. 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 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
      The estimated duration of the activity in minutes.
    • Title: End Time
      The predicted or the actual end time of the activity. The time is displayed in the time zone of the resource to which the activity is assigned and is in YYYY-MM-DD HH:MM:SS format.
    • Title: First Manual Operation
      The name of the first manual operation on the activity.
    • Title: First Manual Operation User
      The user who performed the first manual operation on the activity.
    • Title: Language
      The preferred language of the customer. By default, the language that is set for the Login screen is used. The following language codes are accepted: Supported Language Codes.
    • Title: Latitude
      Minimum Value: -90
      Maximum Value: 90
      The geographic latitude coordinate that specifies the location of the activity.
    • Title: Longitude
      Minimum Value: -180
      Maximum Value: 180
      The geographic longitude coordinate that specifies the location of the activity.
    • Title: Master Activity ID
      The identifier of a segmentable activity. It is available for individual segments which have the record type set to 'multiday_activity_segment'. This field is not set for regular activities.
    • 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: Position In Route
      The position of the activity in the route. For not-ordered activities, this field is not present in the response. For ordered activities, a 1-based number is returned.
    • Title: Postal Code
      The postal code of the customer. This field is used for geocoding and must contain a valid address.
    • Title: Record Type
      Allowed Values: [ "regular", "reopened", "prework", "multiday_activity", "multiday_activity_segment" ]
      The type of the activity record. The following values are allowed:
      • regular: This is the default record type for most new activities.
      • prework: This type of record is created if a technician has to perform some work before the actual activity starts.
      • reopened: A record of this type is created when an activity is reopened for some reason.
      • multiday_activity: This record type is created when the 'activityType' indicates that it is a segmentable activity.
      • multiday_activity_segment: A number of records of this type are created for segmentable activities, based on their duration and time slot settings.
    • Title: Reminder Time
      The number of minutes before the activity start time when 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: Resource Time Zone
      The time zone of the resource to which this activity is assigned (for example, Eastern). This is a read-only field and may change when the activity is reassigned to another resource.
    • Title: Resource Time Zone Difference
      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. This field is read-only and may change when the activity is reassigned to another resource.
    • Title: Resource Time Zone IANA Name
      The IANA name of the resource's time zone (for example, America/New_York). This field is read-only and may change when the activity is reassigned to another resource.
    • Title: Service Window End
      The time when the service window ends for the activity. The time is displayed in 'HH:MM:SS' format.

      Service window is returned in the time zone of the resource to which the activity is currently assigned.

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

      Service window is returned in the time zone of the resource to which the activity is currently assigned.

    • 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.

      SLA window is returned in the time zone of the resource to which the activity is currently assigned.

    • 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.

      SLA window is returned in the time zone of the resource to which the activity is currently assigned.

    • Title: Start Time
      The estimated time of arrival for the activities in 'pending' status and the actual start time for the activities in 'started' and 'completed' status. The time is displayed in 'YYYY-MM-DD HH:MM:SS' format in the time zone of the resource to which the activity is assigned.
    • Title: State Province
      The state or province of the customer. This field is used for geocoding and must contain a valid address.
    • Title: Status
      Allowed Values: [ "cancelled", "completed", "suspended", "started", "pending", "notdone" ]
      The status of the activity. As a technician works through the activity, the status changes. The actions that are available for an activity are based on this status.

      A newly created activity has the status as 'pending', but it can then be changed to 'cancelled' or 'started'. The status of an activity can be changed to 'complete', 'notdone', or 'suspended' only if it has the status as 'started'.

    • 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 Delivered End
      The end time of the technician's arrival interval as communicated to the customer. This time is displayed in the time zone of the resource to which the activity is assigned.
    • Title: Time Delivered Start
      The start time of the technician's arrival interval as communicated to the customer. This time is displayed in the time zone of the resource to which the activity is assigned.
    • Title: Time Of Assignment
      The time when the activity is assigned to the technician. This time is displayed in the time zone of the resource to which the activity is assigned.
    • 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. The time slot also indicates the service window for the activity.
    • Title: Time Zone
      The name of the customer's time zone. For example, Eastern.

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

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

    • Title: Time Zone IANA name
      The IANA name of the time zone. For more information, visit https://www.iana.org/time-zones. For example, America/New_York. This field is read-only, but when creating or updating an activity, the field 'timeZone' accepts both IANA names and Oracle Field Service Cloud specific names.
    • Title: Travel Time
      Read Only: true
      The estimated time taken to travel to this activity. The estimate is based on the previous activity in route.
    • Title: Work Zone
      The work zone in which the activity occurs. It is a read-only field that is automatically assigned to an activity, based on the company setting 'work zone key' and the activity properties. For example, if 'work zone key' is the first 4 symbols of the 'city' field, then the activity with city=Belfast will have a work zone assigned which has 'BELF' as one of its keys.

    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 get resource route for resources by submitting a GET request on the REST resource.

    cURL Command Example

    curl -X GET \
     'https://<instance_name>.etadirect.com/rest/ofscCore/v1/resources/routing/routes/2018-06-27?activityFields=resourceId,resourceInternalId,apptNumber,activityId,city' \
     -H 'Authorization: Basic YWRtaW5Ab2ZzYy01NmZlNTcudGVzdDox' \
     -H 'Cache-Control: no-cache'

    Example of Response Header

    The following shows an example of the response header.

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

    Example of Response Body

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

    {
     "totalResults": 2,
     "limit": 100,
     "offset": 0,
     "items": [
     {
     "activityId": 4225452,
     "resourceId": "ASIA",
     "resourceInternalId": 8101693
     },
     {
     "activityId": 4225453,
     "resourceId": "ASIA",
     "resourceInternalId": 8101693,
     "apptNumber": "10024",
     "city": "New York"
     }
     ],
     "links": [
     {
     "rel": "canonical",
     "href": "https://<instance_name>.etadirect.com/rest/ofscCore/v1/resources/ASIA/routes/2018-06-27?activityFields=resourceId%2CresourceInternalId%2CapptNumber%2CactivityId%2Ccity"
     },
     {
     "rel": "describedby",
     "href": "https://<instance_name>.etadirect.com/rest/ofscCore/v1/metadata-catalog/resources"
     }
     ]
    }
    
    Back to Top