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

Get activities

get

/rest/ofscCore/v1/activities

This operation retrieves a list of activities that match the criteria specified in the request.

This operation is subject to the following conditions:

  • Number of Requests:
    • The maximum number of 'Get activities' requests than can be sent simultaneously is three. If more than three requests are sent, then the additional requests are queued.
    • The maximum number of requests that can be queued is 10. Any additional requests are rejected with an error message.
    • The maximum wait time of a request in the queue is 30 seconds. If the waiting time exceeds 30 seconds, an error message is returned.
  • Number of Activities Returned: The maximum number of activities that can be retrieved in a single response is 100,000. If the value specified for the 'limit' parameter is greater than the maximum number, then the value 100,000 limit is used for limit parameter.
  • Date Range: The maximum date range that can specified for a single request is 31 days. If the date range ('dateTo' - 'dateFrom') exceeds 31 days, then an error message is returned in the response.
  • Response Size: The response for a single request is limited to 20 MB. If the response size is close to 20 MB, the operation returns fewer activities than requested, and the response contains the 'hasMore' flag set to 'true'. This flag indicates that there are more activities to be returned. In this case, a new request with 'offset' parameter set to the last returned item count is sent.
  • Operation Run Time: The maximum run time for a single operation is 30 seconds. When the 30-second time limit is reached, the operation returns fewer activities than requested and the response contains the 'hasMore' flag set to 'true'. This flag indicates that there are more activities to be returned. In this case, a new request with 'offset' parameter set to the last returned item count is sent. If the time limit has exceeded before any activities are included in the response (for example, due to slow database response), an error is returned.
  • Custom Properties Quantity: The maximum number of custom properties used in the request and/or returned in the response is 50. If more than 50 properties are included in the request, an error message is returned. The 50-property restriction includes both the custom properties used in the 'fields' parameter and in the 'q' parameter.

    • Note: the function in some cases may not found existing activities if they has been recently created or bring some activity fields with not actual values if they were recently updated. The following conditions need to be met in order for the function to return the actual data without the latency effect:

    • The request doesn't require filtering by fields except the field status. It means if there is a "q=..." parameter, the query may not return recently created activities. There is one exception to this rule: you can use "q=..." parameter with a single expression status=='' (e.g. status=='pending') exactly in this form. Such expression will allow to get matching activities including recent ones.

    Examples.

    • The following request will return data without latency effect :

    GET https://<environment_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/?resources=tech6121000001&dateFrom=2019-08-14&dateTo=2019-08-14&q=status=='pending'&fields=activityId,resourceId,date,status'

    This request contains query parameter in a form status=='some_status'

    • The following request may miss some recently created activities (latency effect) :

    GET https://<environment_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/?resources=tech6121000001&dateFrom=2019-08-14&dateTo=2019-08-14&q=status != 'cancelled' and activityType in ['IN','TC','BR']&fields=activityId,resourceId,date,status'

    This request contains query parameter in other form then status=='some_status' : it uses != comparison and another field (activityType)

Request

Supported Media Types
Query Parameters
  • The activities that begin from the specified date are retrieved in the response. Specify the date in YYYY-MM-DD format. It is optional if the parameter 'includeNonScheduled' = true. If the dateForm is specified, the dateTo parameter should also be specified.

    Example: https://<environment_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities?dateFrom=2016-09-21&dateTo=2016-09-22

  • The activities that end until the specified date are retrieved in the response. Specify the date in YYYY-MM-DD format. If dateTo is specified, the dateFrom parameter must also be specified.

    Example: https://<environment_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities?dateFrom=2016-09-21&dateTo=2016-09-22

  • Collection Format: csv
    The comma-separated field names that are returned in the response. The field names are the names that you specify when you create an activity or retrieve an activity. The field names can also contain custom property names. 'positionInRoute' cannot be retrieved via API. If the value of this parameter is not specified in the request, then it defaults to: activityId,resourceId,date,status.

    Example: https://<environment_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities?fields=activityId,status,apptNumber,recordType

    Note: If the fields specified in the 'fields' parameter are empty for a given activity, then they are not returned in 'Get Activities' response. For example, if you specify 'fields=apptNumber' and some of the returned activities do not contain apptNumber, then an empty object '{}' is returned in the response.

  • Indicates whether the subordinate resources must be returned.
    • If the value is none, then only the activities assigned to the specified resource are returned.
    • If the value is immediate, then the activities assigned to the specified resource and its first level descendants are returned.
    • If the value is all or if it is not specified, then the activities assigned to the specified resource and its descendants in the hierarchy tree are returned.
    Allowed Values: [ "none", "immediate", "all" ]
  • Indicates whether non-scheduled activities must be returned.
    • If the value is not specified, then non-scheduled activities are not returned.
    • If the value of this parameter is 'true', then the 'dateFrom' and 'dateTo' are not required. If the 'dateFrom' and 'dateTo' parameters are not specified, then only the non-scheduled activities are returned.
    • If the value of this parameter is 'true' and the 'dateFrom' and 'dateTo' parameters are specified, then both the scheduled and non-scheduled activities are returned.
    • If the value of this parameter is 'false' or is not specified, then the 'dateFrom' and 'dateTo' parameters are required, and only the scheduled activities are returned.
  • The number of activities 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,000. If the specified value is greater than 100,000, then it defaults to 100,000.
  • 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.

  • The filter expression applied to the activities in addition to the resource and date filters. Only the activities that match this filter are added to this subscription.

    The following are the filter expression rules:

    • It should be specified as a single string.
    • It should evaluate to a boolean expression.
    • It should contain one or more comparison statements.
      • Syntax of comparison statement: <field> <operator><value>. For example, activityDetails.activityType == 'Install'.
      • The order mentioned in the syntax cannot be changed. For example, ('Install' == activityDetails.activityType) is not a valid comparison statement.
      • The comparision between fields (A == B) or value-to-value (1 == 1) is also not valid.
      • The field has to be an alphanumeric identifier with no spaces or special characters except underscore. The subfields are separated by dot (.). For example:
        • activityDetails.activityType
        • activityDetails.X_MYPROP_10
        • field.subField
    • The following are the supported comparison operators:
      • <
      • >
      • <=
      • >=
      • ==
      • !=
      • in
    • The value of the 'filterExpression' field can be a string literal, an integer literal, or an array literal of strings and integers
      • String literals are delimited by single quotes, with escape character ~, for example:
        • str =='My String'
        • str =='My string with ~' a quote inside'
      • Integer literals are without quotes, they may not contain dot or leading zeroes. For example:
        • num ==0
        • num ==12345
        • num ==-67
      • Array literals must contain only strings or only integers, and are in square brackets. Empty arrays are not allowed. Arrays are only allowed after the "in" operator. For example:
        • enum in [1,2,3]
        • enum in ['Abc','Def','Ghi']
    • String comparisons are valid. For example: date > '2015-06-02'.
    • String comparisons are not case-sensitive. For example: name == 'john.smith' is the same as name == 'JOHN.SMITH'.
    • String to integer coercion is valid. For example: num== -123 is the same as num== '-123'.
    • Multiple comparison statements have to be separated by logical operators (and, or). For example:
      • A == 1 and B == 2 or C == 3
      • A == 'xx' or A == 'yy'
    • The operator precedence is as follows:
      1. comparison operators: ==,!=, <, >, <=, >=, in
      2. 'not'
      3. 'and', 'or'. The logical operators ('and' / 'or') have the same precedence, so parentheses can be used to achieve precedence. For example: A == 1 and (B == 2 or C == 3)
    • Operators are not case-sensitive. For example, (num IN[1,2,3]) OR (num < 0).
    • Any statement can be preceded by "not" operator to negate it. For example:
      • not (activityType in ['IN','TC','BR'])
      • A == 1 and not ( B == 2 or B == 3 )
    • Whitespaces outside strings are ignored.
    • If the field or property is not set, then it evaluates to an empty string. For example, expression null_field == ''.

    Example: GET https://<environment_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities?q=status+%3D%3D+%27pending%27+and+slaWindowEnd+<+%272016-10-23%27

  • Collection Format: csv
    The comma-separated list of resource IDs that are returned in the response. This parameter works in conjunction with the includeChildren parameter.
Back to Top

Response

Supported Media Types

200 Response

This section describes the 200 status response for this operation.
Body ()
Root Schema : Activities
Type: object
Title: Activities
The collection of activities.
Show Source
  • Title: Filter Expression
    The value of the 'q' request parameter parsed by Oracle Field Service.
  • Title: Has More Results
    Contains one of the following values: true or false. If true, then there are more results that can be retrieved with successive paging requests. If false or if the value is not present, then there are no more results or this is the final page. The default value is true.
  • Items
    Title: Items
    The array of activity elements. The structure of this array is same as the array returned by the 'GET activities/{activityId}' operation.
  • Title: Limit
    The limit value specified in the request.
  • Title: Offset
    The offset value specified in the request.
Nested Schema : Items
Type: array
Title: Items
The array of activity elements. The structure of this array is same as the array returned by the 'GET activities/{activityId}' operation.
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. Maximum field length is 1020.

    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 Flow
    Activity flow label
  • Title: Activity ID
    The unique identifier of the activity.
  • Title: Activity Type
    The label of the activity type. 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.
  • 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 and can be left empty. Maximum field length is 40.
  • Title: Auto Routed To Date
    The date to which the activity was moved automatically by routing. Rescheduling the activity does not change this value. It is a read-only field.
  • Title: Auto Routed To Resource
    The external ID of resource to which the activity was last assigned by routing. Reassigning the activity does not change this value. It is a read-only field. If the field has no value, it means that the routing assigned the activity to a resource with empty external ID.
  • Title: City
    The city of the customer where the activity is scheduled. Maximum field length is 60. If a longer value is sent it will be truncated.
  • Title: Coordinate Accuracy
    The coordinate accuracy of the activity. It is a read-only field. The following values are returned:

    • Low
    • Medium
    • High

  • 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. Maximum field length is 240. If a longer value is sent it will be truncated.
  • Title: Customer Email
    The email address of the customer. Maximum field length is 320. If a longer value is sent it will be truncated.
  • Title: Customer Name
    The name of the customer. Maximum field length is 420. If a longer value is sent it will be truncated.
  • 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 and can be left empty. Maximum field length is 40. If a longer value is sent it will be truncated.
  • Title: Customer Phone
    The regular (land) phone number of the customer. From version 17.2.1, the phone number is saved in Oracle Field Service with the '+' symbol. For example, if you enter the phone number as +1(234)234-23_42, it is saved in Oracle Field Service as +12342342342. In versions before 17.2.1, the phone number is saved as 12342342342. Maximum field length is 240. If a longer value is sent it will be truncated.
  • 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
    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: ibAsset Id
    The identifier of the installed based asset the activity is linked to. Optional field. Foreign key to CSE_ASSETS_B.ASSET_ID in Fusion.
  • Title: Language
    The preferred language of the customer. This parameter returns two-character code (e.g. "en") in API responses. To obtain ISO code of the language (e.g. "en-US") read the "languageISO" parameter. In the requests this parameter accepts both formats (e.g. "en" or "en-US"). It is recommended to use ISO format. The language codes listed on: Supported Language Codes.
  • Title: Language ISO
    The preferred language of the customer. This parameter is only present in the responses and will be ignored if it is present in a request. To update language use the parameter "language". The language codes listed on: 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: pjfProject Element Id
    The identifier of the project task the activity is linked to. Optional field. Foreign key to PJF_PROJ_ELEMENTS_B.PROJ_ELEMENT_ID in Fusion.
  • Title: pjfProject Id
    The identifier of the project the activity is linked to. Optional field. Foreign key to PJF_PROJECTS_ALL_B.PROJECT_ID in Fusion.
  • 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. Maximum field length is 60. If a longer value is sent it will be truncated.
  • 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. Maximum field length is 60. If a longer value is sent it will be truncated.
  • Title: Status
    Allowed Values: [ "cancelled", "completed", "suspended", "started", "enroute", "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. Maximum field length is 240. If a longer value is sent it will be truncated.
  • Title: svcWorkOrder Id
    The identifier of the fusion service work order the activity is linked to. Optional field. Foreign key to SVC_WORK_ORDERS.WO_ID in Fusion.
  • 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. The value is used by routing optimization engine to reduce changes to arrival time, so it is important to keep the value actual. This 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: Time Delivered Start
    The start time of the technician's arrival interval as communicated to the customer. The value is used by routing optimization engine to reduce changes to arrival time, so it is important to keep the value actual. This 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: 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 specific names.
  • Title: Travel Estimation Method
    The travel estimation method. It is a read-only field. The following values are returned:

    • Airline Distance
    • Airline Distance and Statistics
    • External Adjustment
    • Manual Adjustment
    • Not Estimated
    • Point to Point
    • Same Location
    • Statistics
    • Street Level Routing
    • Travel key based Airline Distance
    • Using Defaults

  • Title: Travel Time
    Read Only: true

    The estimated time taken to travel to this activity. For activities that were started (status is 'started', 'completed', 'notdone') this parameter indicates reported travelling time, which is calculated based on the actual times.

    Notice that reported travelling time keeps the paid part of the travelling time and may be different from the value shown in UI, depending on the "Travel Allowance" configuration of resource type.

    (Exception : the "activityChanges" object of activity events always brings the full value of the travelling time).

  • Title: wieWorkOrder Id
    The identifier of the maintenance work order the activity is linked to. Optional field. Foreign key to WIE_WORK_ORDERS_B.WORK_ORDER_ID in Fusion.
  • Title: wieWorkOrderOperation Id
    The identifier of the maintenance work order operation the activity is linked to. Optional field. Foreign key to WIE_WO_OPERATIONS_B.WO_OPERATION_ID in Fusion.
  • 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
Show Source
Back to Top

Examples

The following example shows how to view activities by submitting a GET request on the REST resource using cURL. 

curl -s -u '<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>'  --url 'https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/?dateFrom=2017-11-01&dateTo=2017-11-30&resources=22&q=apptNumber+%3D%3D+%27XXXXX%27&fields=activityId,resourceId,timeSlot,date,status

Example of Response Header

The following shows an example of the response header.

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Mon, 18 Dec 2017 02:20:33 GMT
Content-Type: application/json; charset=utf-8
Connection: close

Example of Response Body

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

{
    "expression": "(apptNumber == 'XXXXX')",
    "items": [
        {
            "activityId": "4225371",
            "resourceId": "routing",
            "timeSlot": "",
            "date": "2017-11-16",
            "status": "pending"
        },
        {
            "activityId": "4225372",
            "resourceId": "routing",
            "timeSlot": "",
            "date": "2017-11-16",
            "status": "pending"
        },
        {
            "activityId": "4225373",
            "resourceId": "Arslan_Ates",
            "timeSlot": "",
            "date": "2017-11-16",
            "status": "pending"
        },
        {
            "activityId": "4225374",
            "resourceId": "Arslan_Ates",
            "timeSlot": "08-10",
            "date": "2017-11-16",
            "status": "pending"
        },
        {
            "activityId": "4225375",
            "resourceId": "Arslan_Ates",
            "timeSlot": "08-10",
            "date": "2017-11-16",
            "status": "pending"
        }
    ]
}
Back to Top