REST API for Oracle Field Service Cloud Service

Update activity duration statistics

patch

/rest/ofscStatistics/v1/activityDurationStats

This operation updates the activity duration override for the activity duration key that is currently active.

It is possible to override the activity duration either at the company level, bucket level or at the technician level. To override the activity duration at the company level, the 'resourceId' field must be empty.

If there are multiple activity duration keys configured in the application, the overrides are applicable only to the activity duration key that is currently active. If the activity duration key is modified, then the overrides for that key are deleted from the application. However, the overrides persist if another activity duration key is active, with the old key in the application being inactive state. If the inactive key is set to active again, the overrides that were set corresponding to that key become applicable for the duration estimates.

For the activity duration key that is currently active, the override value is stored in the application along with the statistically learned value. For activity duration estimates, if an override is specified, then the override value is used instead of the statistically learned value. However, the statistically learned value is updated based on the new durations reported. At any point of time, it is possible to stop using the overrides by importing the data again with value 0 in the 'override' field. In such cases, the application starts using the statistically learned value for the duration estimates.

Note:

When the Statistics API is used to make activity duration changes, the changes are reflected for all future activities in the application only after the next run of the statistics agent. The statistics agent is run once a day, usually in the early morning hours.

The limit for each API request is 10000 records. To update more records, multiple requests can be used.

The operation can be used only when the following conditions are satisfied:

The customer must have a subscription to Oracle Field Service Professional or Enterprise Cloud Service.
The required application must have permission to access the Statistics API. To grant the permission, navigate to Configuration, Applications screen. For the required application, click Add new in the API access section, and select Statistics API.

Request

This section describes the request body parameters for this operation.

Root Schema : activityDurationRequestList

Type: object

The schema of the request body object for this operation.

Show Source

items(required): array items

Minimum Number of Items: 1

Maximum Number of Items: 10000

{
    "description":"The schema of the request body object for this operation.",
    "properties":{
        "items":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/activityDurationRequest"
            },
            "minItems":"1",
            "maxItems":"10000"
        }
    },
    "required":[
        "items"
    ]
}

Nested Schema : items

Type: array

Minimum Number of Items: 1

Maximum Number of Items: 10000

Show Source

Array of: object Activity Duration Request

Title: Activity Duration Request

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/activityDurationRequest"
    },
    "minItems":"1",
    "maxItems":"10000"
}

Nested Schema : Activity Duration Request

Type: object

Title: Activity Duration Request

Show Source

akey(required): string

Title: Appointment Key

Maximum Length: 50

The value of the activity duration key. It appears as 'Appointment Key' in the report.
override(required): integer

Minimum Value: 0

Maximum Value: 1440

The override value that needs to be set for the 'resourceId' and 'akey' combination. For example, 100.
resourceId(required): string

Title: Resource ID

Maximum Length: 32

The external ID of the resource. If this value is not provided, the override will be performed at the company level.

{
    "type":"object",
    "title":"Activity Duration Request",
    "properties":{
        "resourceId":{
            "type":"string",
            "title":"Resource ID",
            "maxLength":"32",
            "description":"The external ID of the resource. If this value is not provided, the override will be performed at the company level."
        },
        "akey":{
            "type":"string",
            "maxLength":"50",
            "title":"Appointment Key",
            "description":"The value of the activity duration key. It appears as 'Appointment Key' in the report."
        },
        "override":{
            "type":"integer",
            "minimum":"0",
            "maximum":"1440",
            "description":"The override value that needs to be set for the 'resourceId' and 'akey' combination. For example, 100."
        }
    },
    "required":[
        "resourceId",
        "akey",
        "override"
    ]
}

Response

Supported Media Types

application/json
application/schema+json

200 Response

This section describes the 200 status response for this operation.

Root Schema : activityDurationPatchResponse

Type: object

Show Source

results: object results

{
    "type":"object",
    "properties":{
        "results":{
            "type":"object",
            "properties":{
                "status":{
                    "description":"The HTTP status code.",
                    "type":"string"
                },
                "updatedRecords":{
                    "description":"The number of records updated by the request.",
                    "type":"integer"
                }
            }
        }
    }
}

Nested Schema : results

Type: object

Show Source

status: string

The HTTP status code.
updatedRecords: integer

The number of records updated by the request.

{
    "type":"object",
    "properties":{
        "status":{
            "description":"The HTTP status code.",
            "type":"string"
        },
        "updatedRecords":{
            "description":"The number of records updated by the request.",
            "type":"integer"
        }
    }
}

Default Response

This section describes the default error response for this operation.

Root Schema : Error

Type: object

Show Source

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.

{
    "properties":{
        "type":{
            "type":"string",
            "description":"The URL of the web page containing more details about this error."
        },
        "title":{
            "type":"string",
            "description":"The brief description of this error."
        },
        "status":{
            "type":"string",
            "description":"The HTTP status code of this error."
        },
        "detail":{
            "type":"string",
            "description":"The detailed description of this error."
        }
    },
    "required":[
        "type",
        "title"
    ]
}

Examples

The following example shows how to set or update the activity duration override for activity duration keys by submitting a PATCH request on the REST resource using cURL:

cURL command Example

curl -X PATCH \
  https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscStatistics/v1/activityDurationStats \
  -u '<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>' \
  -H 'content-type: application/json' \
  -d '{
	"items": [
   {
       "resourceId": "routing_bucket_D-Tech-11",
         "akey": "79765",
         "override": 150
   },
   {
       "resourceId": "routing_bucket_D-Tech-12",
         "akey": "79763",
         "override": 130
   }]
}

Response Header Example

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

Response Body Example

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

{
    "status": "OK",
    "updatedrecords": 2
}