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

Get events

get

/rest/ofscCore/v1/events

This operation retrieves a list of events related to a subscription starting from the marker represented by the 'page' request parameter. Also it provides new marker, which should be used to retreive next portion of events.

If there are no new events available, then the operation returns an empty list.

Each next request should use the marker value ('page' parameter) obtained from the previous request ('nextPage' parameter). Initial value of the marker is obtained from 'Create subscription' API call.

Another way to obtain the 'page' value is to perform request using the 'since' parameter that allows to find the value of the 'page' marker by the time. Use this ability only to restore broken flow, as this operation requires significant resources.

The integration must ensure that the events are read faster then generated, Otherwise the integration will not be able to read all the events in time and eventually old events will be lost. It is recommended to read next portion of events after a few seconds for subscriptions with big amount of events or a few minutes for subscriptions with rare events.

Only the events matching the subscription's filter are returned.

If the client application loses the value of the 'page' parameter due to abnormal process termination, the last requested 'page' parameter can be recovered through the disaster recovery flow. For more information, see the 'Recovering lost page parameter' section under Receiving Events.

Note: Getting events is only allowed for the application which was used to create the subscription.

Request

Supported Media Types
Query Parameters
  • The number of items to be returned in the response. The maximum value is 1000. If a higher value is specified, then the value will be set to the maximum allowed value and the specified value is ignored.
  • The page identifier to iterate the events. The value of the parameter is set to the value of the 'nextPage' element returned by a previous call to this operation. If this parameter is not specified, then an empty response is returned along with a new 'nextPage' element, which can be used in subsequent requests.

    The value of the 'page' parameter can be set to 'lastRequested' to return items from the same position as the last successful request. Setting the value of the page to 'lastRequested' is equivalent to setting the value of the page to 'XXX' where XXX is the last requested page.

    If the value of the page specified in the first request is 'lastRequested', then the response will contain events from the page value returned by the 'Create subscription' operation.

    The value of this parameter should be either special word "lastRequested" or the exact string as returned by "nextPage" response attribute of a previous call. There is no specification for the value format - it may be any string not longer than 48 characters. Do not interfere the value, as the incorrect values may result with valid response but the events sequence may be distorted.

  • This parameter is used to obtain new 'page' marker that points at the events which happened after the specified time. The time value must be specified in 'YYYY-MM-DD HH:MM:SS' format and UTC time zone.

    When this parameter is specified in the request, the events are not returned, but only 'nextPage' response parameter. Do not use both 'page' and 'since' parameters in one request.

    This functionality should be used only to restore broken flows and to start reading from some point in time when normal reading failed. Never use this ability to access the events by their time, as this ability requires significant resources and may slow down other system functions if used extensivly.

    Note that obtaining events from a subscription which happened before the subscription was created is not supported. The system starts collecting the events only after the subscription is created. Trying to read events that are older may result in obtaining some information but it is not guaranteed.

  • The identifier of a previously created subscription. This is a mandatory parameter. Only the events matching the subscription's filter are returned in the response.
Back to Top

Response

Supported Media Types

200 Response

This section describes the 200 status response for this operation.
Body ()
Root Schema : Events Collection
Type: object
Title: Events Collection
The collection of events.
Show Source
  • items
  • Title: Next Page
    The next page identifier passed to the next request for obtaining the next series of events.

    There is no specification for the value format - it may be any string not longer than 48 characters.

Nested Schema : items
Type: array
Show Source
Nested Schema : Event
Type: object
Title: Event
The array of events.
Show Source
Match All
Show Source
Nested Schema : Request Event
Type: object
Title: Request Event
The object containing details of the request event.
Show Source
Match All
Show Source
Nested Schema : Inventory Event
Type: object
Title: Inventory Event
The object containing details of the inventory event.
Show Source
Match All
Show Source
Nested Schema : Route Event
Type: object
Title: Route Event
The object containing details of the route event.
Show Source
Match All
Show Source
Nested Schema : Activity Event
Type: object
Title: Activity Event
The object containing details of the activity event.
Show Source
Match All
Show Source
Nested Schema : userEvent
Type: object
Show Source
Match All
Show Source
Nested Schema : resourceEvent
Type: object
Show Source
Match All
Show Source
Nested Schema : Chat Updated
Type: object
Title: Chat Updated
The object containing details of the chat updated event.
Show Source
Match All
Show Source
Nested Schema : Chat Message Sent
Type: object
Title: Chat Message Sent
The object containing details of the Chat Message Sent event.
Show Source
  • Chat
    Title: Chat
    The object containing details about the chat.
  • Message
    Title: Message
    The object containing the details of a message.
  • Participants
    Title: Participants
    A record containing the details of the participants in the chat or broadcast. This field is available only when the message is the first message of a chat or a broadcast.
Match All
Show Source
Nested Schema : Broadcast Status Update
Type: object
Title: Broadcast Status Update
The event occurs when the broadcast status of a participant is changed.
Show Source
Match All
Show Source
Nested Schema : Transaction Updated
Type: object
Title: Transaction Updated
The event occurs whenever an operation is done on a transaction through Collaboration. A transaction through Collaboration is the transfer of an inventory or activity through chat.
Show Source
Match All
Show Source
Nested Schema : Activity Link Event
Type: object
Title: Activity Link Event
The object containing details of the activity link event.
Show Source
Match All
Show Source
Nested Schema : Resource Preference Event
Type: object
Title: Resource Preference Event
The object containing the details of the resource preference event.
Show Source
Match All
Show Source
Nested Schema : Route Run Event
Type: object
Title: Route Run Event
The object containing details of the routing run event.
Show Source
Match All
Show Source
Nested Schema : Event Generic Fields
Type: object
Title: Event Generic Fields
The list of generic fields of the event.
Show Source
  • Title: Event Type
    Allowed Values: [ "activityCreated", "activityUpdated", "activityStarted", "activityTravelStarted", "activityTravelStopped", "activitySuspended", "activityCompleted", "activityNotDone", "activityCanceled", "activityDeleted", "activityDelayed", "activityReopened", "activityPreworkCreated", "activityLinkCreated", "activityLinkDeleted", "resourcePreferenceCreated", "resourcePreferenceDeleted", "requiredInventoryCreated", "requiredInventoryUpdated", "requiredInventoryDeleted", "inventoryInstalled", "inventoryDeinstalled", "customerInventoryCreated", "customerInventoryUpdated", "customerInventoryDeleted", "inventoryUndoInstall", "inventoryUndoDeinstall", "activityMoved", "routeCreated", "routeUpdated", "routeActivated", "routeDeactivated", "routeReactivated", "customerRequestCreated", "inventoryRequestCreated", "resourceRequestCreated", "chatUpdated", "chatMessageSent", "userUpdated", "userCreated", "userDeleted", "resourceUpdated", "resourceCreated", "transactionUpdated", "resourceInventoryCreated", "resourceInventoryUpdated", "resourceInventoryDeleted", "routingRun", "broadcastStatusUpdate", "formSubmitted" ]
    The type of the event.
  • Title: Time
    The event time is in the UTC time zone and in the 'YYYY-MM-DD HH:MM:SS' format.
  • Title: User
    The login name of the user who performed the action that triggered the event.

    Note: Some actions are performed by the Oracle Field Service application. Therefore, the parameter is not returned, if the action is not performed by the user.

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 get events by submitting a GET request on the REST resource using cURL.

curl -H 'Accept: application/json' \
'https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/events?subscriptionId=a0fd97e62abca26a79173c974d1e9c19f46a254a&page=160425-457%2C0'

Example of Request Header

The following shows an example of the resquest header.

GET /rest/ofscCore/v1/events?subscriptionId=a0fd97e62abca26a79173c974d1e9c19f46a254a&page=160425-457%2C0 HTTP/1.1
Connection: close
Accept-Encoding: gzip,deflate
Authorization: Basic bXlyb290QHFhNTUwMzox
Host: <instance_name>.fs.ocs.oraclecloud.com
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Example of Response Header

The following shows an example of the response header.

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 25 Apr 2016 12:36:21 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: close

Example of Response Body

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

{
     "found": true,
     "nextPage": "180404-706,1",
     "items": [
         {
             "eventType": "routingRun",
             "time": "2018-04-04 21:10:33",
             "user": "admin",
             "routingRunDetails": {
                 "routingPlan": "Bulk Routing",
                 "routingPlanLabel": "BulkRouting",
                 "routingPlanId": 1,
                 "result": "succeeded",
                 "startType": "manual",
                 "type": "routing",
                 "resourceId": 1000000,
                 "routingRunId": 27023,
                 "targetDate": "2018-04-04",
                 "numberOfDays": 1,
                 "routingProfile": "Routing (Region 3-5)",
                 "routingProfileLabel": "Routing_Region_3_5",
                 "routingProfileId": 1,
                 "routingRunDuration": 2,
                 "activitiesMatched": 11,
                 "activitiesRouted": 0,
                 "activitiesNotRouted": 11,
                 "resourcesMatched": 97,
                 "resourcesUsed": 1,
                 "averageWorkingTime": 104,
                 "averageOverTime": 224,
                 "averageTravelTime": 120,
                 "averageDownTime": 0
             }
         }
     ],
     "links": [
         {
             "rel": "describedby",
             "href": 
"https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/metadata-catalog/events"
         },
         {
             "rel": "canonical",
             "href": 
"https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/events/?subscriptionId=50bb8eb8f0cf12145f325a31b40cc15906a67bd2&page=180404-706,0"
         },
         {
             "rel": "next",
             "href": 
"https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/events/?subscriptionId=50bb8eb8f0cf12145f325a31b40cc15906a67bd2&page=180404-706,1"
         }
     ]
}
Back to Top