1. REST API for Oracle Field Service Cloud Service
  2. Tasks
  3. Core
  4. Activities

Where is my technician

get

/rest/ofscCore/v1/whereIsMyTech

This operation provides integrators with a unified method to retrieve activity status and technician information in a single request. This API can be used only when the following conditions are met:

  • The customer must have a subscription to Oracle Field Service Customer Communication Cloud Service, Oracle Field Service Professional Cloud Service, or Oracle Field Service Enterprise Cloud Service.
  • The permission to access Core API for Activity is granted in the Configuration > Applications > API access section of the required application.

If either of the conditions are not met, the '403 Forbidden' error message is returned.

Note: The operation takes the activity ID as the required parameter. If a mass/repeating activity is used, then it should be instantiated as it does not have an ID otherwise. The operation is not designed for segmentable activities, but it can work with individual segments as a single activity. Segmentable master activities should not be used with the operation as their statuses have a different flow and the result of the operation can be different from that of the other activities.

Request

Query Parameters
  • Collection Format: csv
    The comma-separated names of activity fields (properties) that are returned in the response. This parameter is ignored for the activity fields 'startTime', 'timeZoneDiff' and the 'timeZoneIANA'. These fields will be present in the response when the startTime is known or estimated.
  • The unique identifier of the activity in Oracle Field Service.
  • Time in minutes from a previous completed activity or from the queue activation, during which the technician location coordinates shouldn't be returned. Minimum value = 0, Maximum = 60, Default = 0.
  • Contains one of the following values: true or false. If true, then the response contains the image binary data encoded in Base64 format. If false, then the response does not contain the image binary data encoded in Base64 format. The default value is false.
  • Collection Format: csv
    The comma-separated names of the resource fields (properties) that are returned in the response. This parameter is ignored for the 'resourceName' and 'avatar' fields. The name and avatar of a technician will be present in the response when the activity already assigned.
Back to Top

Response

Supported Media Types

200 Response

This section describes the 200 status response for this operation.
Body ()
Root Schema : Activity and Technician Status
Type: object
Title: Activity and Technician Status
The data structure containing information about the activity and technician.
Show Source
  • activityDetails
    The data structure containing the activity details.
  • coordinates
    The data structure containing the geographic coordinates of the technician's location. This field is present only when the value of the 'status' parameter is either 'onTheWay' or 'started'. The field values are specified as floating point numbers with a maximum of five digits after the decimal point.
  • resourceDetails
    The data structure that contains the resource information.
  • Title: Status
    Allowed Values: [ "notAssigned", "assigned", "onTheWay", "started", "notdone", "cancelled", "completed" ]

    The status of the technician or the activity.

    • The value is 'notAssigned' when the activity is not assigned to the technician and the activity status is 'pending'. The technician details and the geographic coordinates of the technician's location are not returned. In the activity details, the fields requested in the activityFields parameter are returned but the start time and the time zone information is not returned.
    • The value is 'assigned' when the activity has been assigned to a technician, but the technician may have other work to finish first. The technician details are returned but the geographic coordinates of the technician's location are not returned. In the activity details, the fields requested in the activityFields parameter along with the start time are returned.
    • The value is 'onTheWay' when there is a new activity in the technician's route and the previous activity (if exists) is in a final status. The technician details along with the geographic coordinates of the technician's location are returned. In the activity details, the fields requested in the activityFields parameter along with the start time are returned.
    • The value is 'started' when the technician has started the activity. The technician details along with the geographic coordinates of the technician's location are returned. In the activity details, the fields requested in the activityFields parameter along with the start time are returned.
    • The value is 'notDone' when the activity status is 'notdone'. The technician details are returned but the geographic coordinates of the technician's location are not returned. In the activity details, the fields requested in the activityFields parameter along with the start time are returned.
    • The value is 'complete' when the activity status is 'complete'. The technician details are returned but the geographic coordinates of the technician's location are not returned. In the activity details, the fields requested in the activityFields parameter along with the start time are returned.
    • The value is 'cancelled' when the activity status is 'cancelled'. The technician details are returned but the geographic coordinates of the technician's location are not returned. In the activity details, the fields requested in the activityFields parameter are returned while the start time is not returned.
Nested Schema : activityDetails
Type: object
The data structure containing the activity details.
Show Source
  • The unique identifier of the activity in Oracle Field Service.
  • The estimated start time for activities that are in 'pending' status. The actual start time for activities that are in 'started', 'completed', or 'notDone' status. The date and time (in UTC time zone) is in 'YYYY-MM-DD HH:MM:SS' format.
  • The difference between UTC and the customer's local time, displayed in minutes. For example, -180 means that customer's time is 3 hours behind UTC.
  • The IANA name of the customer's time zone (for example, America/New_York). For the list of IANA time zone names, see IANA Time Zones.
Nested Schema : coordinates
Type: object
The data structure containing the geographic coordinates of the technician's location. This field is present only when the value of the 'status' parameter is either 'onTheWay' or 'started'. The field values are specified as floating point numbers with a maximum of five digits after the decimal point.
Show Source
  • The latitude coordinate (in degrees) of the technician's location.
  • The longitude coordinate (in degrees) of the technician's location.
  • The time (ISO 8601 compatible) when the geographic coordinates were collected.
Nested Schema : resourceDetails
Type: object
The data structure that contains the resource information.
Show Source
  • avatar
    The data structure that contains the avatar information of the technician. If the 'avatar' property is empty, then this object is not returned. It is also not returned until the activity is assigned to a specific technician.
  • The name of the technician.
Nested Schema : avatar
Type: object
The data structure that contains the avatar information of the technician. If the 'avatar' property is empty, then this object is not returned. It is also not returned until the activity is assigned to a specific technician.
Show Source
  • The filename of the image.
  • The URL of the image.
  • The Base64 encoded image data. It is only returned if the technician has an avatar photo, and the parameter 'includeAvatarImageData' is set to 'true' in the request.
  • The format of the file ('image/jpeg', 'image/png').
  • The field contains the constant value 'picture'.

Default Response

This section describes the default error response for this operation.
Body ()
Root Schema : Error
Type: object
Show Source
Back to Top

Examples

The following example shows how to retrieve activity status and technician information in a single call by submitting a GET request on the REST resource using cURL.

curl -u '<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>' 'https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/whereIsMyTech?activityId=12345&includeAvatarImageData=true&resourceFields=STAR_RATING'

Example of Response Header

The following shows an example of the response header.

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Fri, 10 Jan 2018 02:20:33 GMT
Content-Type: application/json; charset=utf-8
Connection: close

Example of Response Body

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

{
    "status": "onTheWay",
    "coordinates": {
        "time": "2017-12-14 06:30:00+0000",
        "latitude": 64.2807,
        "longitude": -51.86598
    },
    "resourceDetails": {
        "name": "Bruce Key",
        "STAR_RATING": "4.8",
        "avatar": {
            "imageData": "iVBORw0KGgoAAAANSUhEUgAAAOEAA...long-string-truncated-for-brevity",
            "filename": "AVATAR.png",
            "mediaType": "image/png",
            "rel": "picture",
            "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/users/bruce.key/avatar"
        }
    },
    "activityDetails": {
        "activityId": 8760513,
        "startTime": "2017-12-04 08:46:00",
        "timeZoneDiff": -300,
        "timeZoneIANA": "America/New_York"
    }
}
Back to Top