REST API for Oracle Field Service Cloud Service

Routing Events

The following routing event can be specified as part of the request for creating a subscription:

Event	Description
routingRun	This event type allows integrators to build flows depending on the routing execution stages and reduces the necessity to watch and monitor routing execution processes in the Manage interface.

An external system can subscribe to the new event type using the 'Create subscription' function. Additionally, the subscribing application can use the 'filterExpression' field to narrow the event scope depending on the flow.

Note:

The 'fields' parameter for the 'Create subscription' function for this event type will not affect the response of the 'Get events' function.

Event Fields

The routing event contains the following fields:

eventType (string): The type of the event. For this event, the value is 'routingRun'.
time (string): The time of the event in UTC time zone. The time format is YYYY-MM-DD HH:MM:SS.
user (string):
- When routing is started manually by the user, the value is the login value of the user who started it.
- When routing is started automatically, the value is an empty string.
routingRunDetails: This object contains the following fields:
- routingRunId (int): The unique ID of the specific routing run.
- type (string): Reserved for Oracle Field Service internal use. The field shall be removed in a future release.
- startType (string): Indicates the type of routing start and has one of the following values:
  - When routing is started automatically on schedule, the value is 'automatic'.
  - When routing is started manually by user, the value is 'manual'."
- result (string): The result of the routing execution. Can contain one of the following values:
  - When the routing is executed successfully, and some activities are moved as a result, the value is 'succeeded'.
  - When the routing execution is stopped by the user, the value is 'stopped'.
  - When the routing execution fails, the value is 'failed'."
- targetDate (string): The date for which the activities are routed. The format is 'YYYY-MM-DD'.
- numberOfDays (int): For a single day routing, the value is 1. For multi-day routing, the value is the number of days routed, starting from 'targetDate' and going into the future.
- resourceExternalId (string): The external ID of the routing bucket.
- resourceId (int): The internal ID of the routing bucket.
- routingPlan (string): The name of the routing plan that was executed. It is not unique.
- routingPlanId (int): The unique ID of the routing plan that was executed.
- routingPlanLabel (string): The unique label of the routing plan that was executed.
- routingProfile (string): The name of the routing profile that the routing plan belongs to. It is not unique.
- routingProfileId (int): The unique ID of the routing profile that the routing plan belongs to.
- routingProfileLabel (string): The unique label of the routing profile that was executed.
- routingRunDuration (int): The duration (in seconds) of the routing run.
- activitiesMatched (int): The number of activities and per-existing activity segments matching the routing plan filters.
- activitiesRouted (int): The number of activities scheduled and assigned by the routing run.
- resourcesMatched (int): The number of resources matching the routing plan filters.
- resourcesUsed (int): The number of resources with assigned or removed activities by the routing run.
- activitiesInRoutesBeforeRouting (int): The number of activities and pre-existing activity segments that were in routes of resources before the routing run.
- reoptimizedActivities (int): The number of activities re-optimized by the routing run.
- createdActivities (int): The number of activities that were created automatically for the routing run.
- removedActivities (int): The number of removed activities, that my be warehouse visits or activity segments.
- activitiesNotRouted (int): The number of activities matching the routing plan filters but not routed.
- startTime (string): The time when the routing run started in UTC time zone. The time format is YYYY-MM-DD HH:MM:SS.
- assurancePercentage (double): The assurance of routing result, from 0 to 100. The lesser assurance is, the less confident is the result, which, in most cases, may be connected to sub-optimal results. Typically, for good results the assurance may be 85 or more.
- consumedTime (int): The time (in seconds) that was consumed by SLR and routing engine during the routing run.
- routingPlanTimeLimit (int): Time limit for the routing plan (in seconds).
- routingPlanOptimizationGoal (string): If there is an optimization goal at the routing run, the field shows the goal. The possible values are:
  - balanced
  - minimize_travel
  - maximize_jobs
  - maximize_jobs_density
  - reduce_overdue
- routingPlanTimeLimitSlrPercentage (int): Part of total time limit which is the time limit for SLR service.
- averageWorkingTime (int): The average working time of the resources (in minutes).
- averageOverTime (int): The average overtime time of the resources (in minutes).
- averageTravelTime (int): The average travel time of the resources (in minutes).
- averageDownTime (int): The average downtime time of the resources (in minutes).
- averageMileage (int): The average travel mileage of the resources (in miles or km).
- notAssignedDueToValidationIssuesCount (int): Reason for non-assignment: Configuration/data validation errors.
- notAssignedDueToActivityConfigurationCount (int): Reason for non-assignment: Configuration of an activity.
- notAssignedDueToResourcesConfigurationCount (int): Reason for non-assignment: Configuration of resources.
- notAssignedNeedsManualAssignmentCount (int): Reason for non-assignment: Constraint violation. Try to assign the activity manually.
- notAssignedOtherIssuesCount (int): Other reasons for non-assignment.
- notAssignedNeedsOvertimeOverdueRulesRelaxationCount (int): Reason for non-assignment: Overtime/overdue constraint violation. Try to assign manually with relaxed constrains or just relax business rules on overdue/overtime for the routing plan.
- notAssignedDueToChangesWhileRoutingWasRunningCount (int): Reason for non-assignment: Changes while the routing was running.
- partiallyAssignedSegmentableActivitiesCount (int): Partially assigned segmentable activities.
- notAssignedDueToDynamicModeRestrictionsCount (int): Activities were not assigned in accordance with routing plan dynamic mode settings.
- notAssignedDueToCostSettingsCount (int): Reason for not-assignment: Routing plan and/or resource type cost settings may be suboptimal.
- notAssignedDueToTravelRestrictionsCount (int): Reason for non-assignment: activity locations and routing plan travel settings prohibits assignment
- notAssignedDueToOptimizationCriteriaCount (int): Activities were not assigned in accordance to optimization criteria chosen.
- resourceBlockedDueToRoutingScheduleCount (int): Resource are blocked by another run as of sub-optimal routing plan schedule.
- extendedStatus (string): Indicates the type of routing execution. The types are 'routing' or 'routing_rollback'.
  If type is 'routing', then next position in the field shows routing algorithm type. The field can have the following values:
  - bulk
  - urgent
  - immediate
  In addition, the next field in the value indicates the result if it differs from possible values of the field. When there are no activities found, the value is 'skipped'. If the result is succeeded but was not applied, the field is set to 'notAccepted'.
  
  Here's a list of various combinations:
  - routing-rollback
  - routing-bulk
  - routing-urgent
  - routing-immediate
  - routing-bulk-skipped
  - routing-bulk-notAccepted
  - routing-immediate-skipped
  - routing-broadcast
- message (string): The field contains the error description when 'result' is 'failed' or 'skipped'. List of possible errors and solutions are available under Troubleshoot Routing in the Using Routing guide.
- subcategory (string): Reserved for future needs.

Examples

The following is an example for creating subscription with event type 'routingRun':

cURL command


POST https://<instance_name>.fs.ocs.oraclecloud.com/events/subscriptions

{
     "subscriptionConfig":[
         {
             "events" : [
                 "routingRun"
             ]
             ,"filterExpression" : "routingRunDetails.routingPlan=='RoutingEventOACplan'"
         }
     ]
}

Response

HTTP/1.1 200 OK

{
     "subscriptionId": "50bb8eb8f0cf12145f325a31b40cc15906a67bd2",
     "nextPage": "180404-706,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/subscriptions/50bb8eb8f0cf12145f325a31b40cc15906a67bd2"
         },
         {
             "rel": "data",
             "href": 
"https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/events/?subscriptionId=50bb8eb8f0cf12145f325a31b40cc15906a67bd2&page=180404-706,0"
         }
     ]
}

The following is an example of 'Get events' call for a event subscription that has event type as 'routingRun':

Request

GET 
https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/events/?subscriptionId=50bb8eb8f0cf12145f325a31b40cc15906a67bd2&page=180404-706,0

Response

{
    "found": true,
    "nextPage": "220723-5041,1",
    "items": [
        {
            "eventType": "routingRun",
            "time": "2022-07-23 19:38:25",
            "user": "ActivitiesBeforeRoutingBucket",
            "routingRunDetails": {
                "routingRunId": 1005972,
                "type": "routing",
                "startType": "manual",
                "result": "succeeded",
                "targetDate": "2022-07-23",
                "numberOfDays": 1,
                "resourceExternalId": "ActivitiesBeforeRoutingBucket",
                "resourceId": 20423,
                "routingPlan": "RoutingEventOACplan",
                "routingPlanId": 174,
                "routingProfile": "RoutingEventOACprofile",
                "routingProfileId": 115,
                "routingRunDuration": 1,
                "activitiesMatched": 1,
                "activitiesRouted": 1,
                "resourcesMatched": 1,
                "resourcesUsed": 1,
                "activitiesInRoutesBeforeRouting": 1,
                "reoptimizedActivities": 0,
                "createdActivities": 0,
                "removedActivities": 0,
                "activitiesNotRouted": 0,
                "startTime": "2022-07-23 19:38:25",
                "assurancePercentage": 99.9,
                "consumedTime": 0,
                "routingPlanTimeLimit": 30,
                "routingPlanOptimizationGoal": "balanced",
                "routingPlanTimeLimitSlrPercentage": 50,
                "averageWorkingTime": 60,
                "averageOverTime": 0,
                "averageTravelTime": 10,
                "averageDownTime": 0,
                "averageMileage": 0,
                "notAssignedDueToValidationIssuesCount": 0,
                "notAssignedDueToActivityConfigurationCount": 0,
                "notAssignedDueToResourcesConfigurationCount": 0,
                "notAssignedNeedsManualAssignmentCount": 0,
                "notAssignedOtherIssuesCount": 0,
                "notAssignedNeedsOvertimeOverdueRulesRelaxationCount": 0,
                "notAssignedDueToChangesWhileRoutingWasRunningCount": 0,
                "partiallyAssignedSegmentableActivitiesCount": 0,
                "notAssignedDueToDynamicModeRestrictionsCount": 0,
                "notAssignedDueToCostSettingsCount": 0,
                "notAssignedDueToTravelRestrictionsCount": 0,
                "notAssignedDueToOptimizationCriteriaCount": 0,
                "resourceBlockedDueToRoutingScheduleCount": 0,
                "extendedStatus": "routing-bulk",
                "subcategory": ""
            }
        }
    ],
    "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
"
        }
    ]
}