Get events
/rest/ofscCore/v1/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
- application/x-www-form-urlencoded
-
limit: integer
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.
-
page: string
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.
-
since: string
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.
-
subscriptionId(required): string
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.
Response
- application/json
200 Response
object
Events Collection
-
found:
boolean
-
items:
array items
-
nextPage:
string
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.
array
-
Array of:
object Event
Title:
Event
The array of events.
object
Event
-
object
allOf
Request Event
Title:
Request Event
The object containing details of the request event. -
object
allOf
Inventory Event
Title:
Inventory Event
The object containing details of the inventory event. -
object
allOf
Route Event
Title:
Route Event
The object containing details of the route event. -
object
allOf
Activity Event
Title:
Activity Event
The object containing details of the activity event. -
object
allOf
userEvent
-
object
allOf
resourceEvent
-
object
allOf
Chat Updated
Title:
Chat Updated
The object containing details of the chat updated event. -
object
allOf
Chat Message Sent
Title:
Chat Message Sent
The object containing details of the Chat Message Sent event. -
object
allOf
Broadcast Status Update
Title:
Broadcast Status Update
The event occurs when the broadcast status of a participant is changed. -
object
allOf
Transaction Updated
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. -
object
allOf
Activity Link Event
Title:
Activity Link Event
The object containing details of the activity link event. -
object
allOf
Resource Preference Event
Title:
Resource Preference Event
The object containing the details of the resource preference event. -
object
allOf
Route Run Event
Title:
Route Run Event
The object containing details of the routing run event.
object
Request Event
-
activityDetails:
object Activity Details
Title:
Activity Details
The object containing the activity details. -
inventoryDetails:
object Inventory Details
Title:
Inventory Details
The object containing the inventory details. -
requestChanges:
object Request Changes
Title:
Request Changes
The object containing the request changes. -
requestDetails:
string
Title:
Request Details
The details of the request.
-
object
Event Generic Fields
Title:
Event Generic Fields
The list of generic fields of the event.
object
Inventory Event
-
activityDetails:
object Activity Details
Title:
Activity Details
The object containing the activity details. -
inventoryChanges:
object Inventory Changes
Title:
Inventory Changes
The object containing the inventory changes. -
inventoryDetails:
object Inventory Details
Title:
Inventory Details
The object containing the inventory details.
-
object
Event Generic Fields
Title:
Event Generic Fields
The list of generic fields of the event.
object
Route Event
-
routeChanges:
object Route Changes
Title:
Route Changes
The object containing the route changes. -
routeDetails:
string
Title:
Route Details
The details of the route.
-
object
Event Generic Fields
Title:
Event Generic Fields
The list of generic fields of the event.
object
Activity Event
-
activityChanges:
object Activity Changes
Title:
Activity Changes
The object containing the activity changes. -
activityDetails:
object Activity Details
Title:
Activity Details
The object containing the activity details. -
moveDetails:
object Move Details
Title:
Move Details
The object containing the move details.
-
object
Event Generic Fields
Title:
Event Generic Fields
The list of generic fields of the event.
object
-
object
Event Generic Fields
Title:
Event Generic Fields
The list of generic fields of the event.
object
-
resourceChanges:
object Resource
Title:
Resource
The resource used for an activity. For example, a resource can be a technician, a truck, or a bucket.Note: This resource is not the same as a REST resource.
-
resourceDetails:
object resourceDetails
-
object
Event Generic Fields
Title:
Event Generic Fields
The list of generic fields of the event.
object
Chat Updated
-
chat:
object Chat
Title:
Chat
The object containing details about the chat. -
participant:
object Participant
Title:
Participant
The participant object contains details about the participant.
-
object
Event Generic Fields
Title:
Event Generic Fields
The list of generic fields of the event.
object
Chat Message Sent
-
chat:
object Chat
Title:
Chat
The object containing details about the chat. -
message:
object Message
Title:
Message
The object containing the details of a message. -
participants:
array 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.
-
object
Event Generic Fields
Title:
Event Generic Fields
The list of generic fields of the event.
object
Broadcast Status Update
-
statusChanges:
object Broadcast Status Update
Title:
Broadcast Status Update
A record containing an array of status update records. Each status update record is a map with the following fields
-
object
Event Generic Fields
Title:
Event Generic Fields
The list of generic fields of the event.
object
Transaction Updated
-
chat:
object Chat
Title:
Chat
The object containing details about the chat. -
message:
object Message
Title:
Message
The object containing the details of a message.
-
object
Event Generic Fields
Title:
Event Generic Fields
The list of generic fields of the event.
object
Activity Link Event
-
activityLinkDetails:
string
Title:
Activity Link Details
The details of the activity link event. -
fromActivityDetails:
object Activity Details
Title:
Activity Details
The object containing the activity details. -
toActivityDetails:
object Activity Changes
Title:
Activity Changes
The object containing the activity changes.
-
object
Event Generic Fields
Title:
Event Generic Fields
The list of generic fields of the event.
object
Resource Preference Event
-
activityDetails:
object Activity Details
Title:
Activity Details
The object containing the activity details. -
resourcePreference:
string
Title:
Resource Preference
The resource preference defined for the activity.
-
object
Event Generic Fields
Title:
Event Generic Fields
The list of generic fields of the event.
object
Route Run Event
-
routingRunDetails:
object Routing Run Changes
Title:
Routing Run Changes
The object containing the routing run changes.
-
object
Event Generic Fields
Title:
Event Generic Fields
The list of generic fields of the event.
object
Event Generic Fields
-
eventType:
string
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. -
time:
string
Title:
Time
The event time is in the UTC time zone and in the 'YYYY-MM-DD HH:MM:SS' format. -
user:
string
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
object
-
detail:
string
The detailed description of this error.
-
status:
string
The HTTP status code of this error.
-
title(required):
string
The brief description of this error.
-
type(required):
string
The URL of the web page containing more details about this error.
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" } ] }