Jump to

• Request
• Response
• Examples

Update airline distance based travel

patch

/rest/ofscStatistics/v1/airlineDistanceBasedTravel

This operation overrides the airline distance based travel time (in minutes) at the travel key level.

For the specified travel key, the application considers the provided pair of distances (in km) and override values (in minutes) to calculate the corresponding override values for all possible distances. Airline distance based travel time for the travel key is based on these values, instead of the estimated values. The override values are stored in the application along with the corresponding statistically estimated values. If overrides are specified, then the override values are used instead of the statistically estimated values. However, the statistically estimated value is updated based on the new travels reported. At any point of time, you can stop using the overrides by importing the data again with value '-1' in one of the 'override' fields. In such cases, the application uses the statistically estimated value for the airline distance based travel time estimates for the travel key.

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

Note: When the Statistics API is used to make airline distance based travel changes, the changes are reflected for all future travels 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.

Before you use this operation, ensure that:

• You have a subscription to Oracle Field Service Professional or Enterprise Cloud Service.
• The application has the permission to access the Statistics API. To grant the permission, navigate to Configuration > Applications screen. For the required application, in the API access section, click Add new and select Statistics API.
• If 'Detect activity travel keys automatically' is checked in Statistics configuration, then this API cannot be used.

Request

Body ()

This section describes the request body parameters for this operation.

Root Schema : airlineDistanceBasedTravelRequestList

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/airlineDistanceBasedTravelRequest"
            },
            "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 Travel Key Request
  Title: Travel Key Request

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

Nested Schema : Travel Key Request

Type: object

Title: Travel Key Request

Show Source

• data(required): array data
  Minimum Number of Items: 1

  Maximum Number of Items: 2
• key(required): string
  Title: Travel Key

  Maximum Length: 50

  The value of the travel key. It appears as 'Start Location' and 'End Location' in the Travel Statistics report.
• keyId: integer
  Title: Key ID

  Maximum Length: 99999

  Key ID of one of the configured travel keys.

  • If 'keyId' is not specified, data corresponding to the default travel key will be updated.
  • If 'keyId' is specified and if it exists in the system, data will be updated for the corresponding key.
  • If 'keyId' is specified but does not exist in the system, an error message will be returned

{
    "type":"object",
    "title":"Travel Key Request",
    "properties":{
        "key":{
            "type":"string",
            "maxLength":50,
            "title":"Travel Key",
            "description":"The value of the travel key. It appears as 'Start Location' and 'End Location' in the Travel Statistics report."
        },
        "data":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/airlineDistanceBasedTravelOverrideData"
            },
            "minItems":1,
            "maxItems":2
        },
        "keyId":{
            "type":"integer",
            "maxLength":99999,
            "title":"Key ID",
            "description":"<p>Key ID of one of the configured travel keys.</p><ul><li>If 'keyId' is not specified, data corresponding to the default travel key will be updated.</li><li>If 'keyId' is specified and if it exists in the system, data will be updated for the corresponding key.</li><li>If 'keyId' is specified but does not exist in the system, an error message will be returned</li></ul>"
        }
    },
    "required":[
        "key",
        "data"
    ]
}

Nested Schema : data

Type: array

Minimum Number of Items: 1

Maximum Number of Items: 2

Show Source

• Array of: object Travel Key Override Data
  Title: Travel Key Override Data

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

Nested Schema : Travel Key Override Data

Type: object

Title: Travel Key Override Data

Show Source

• distance: integer
  Minimum Value: -1

  Maximum Value: 999

  The distance (in km) for which the override value of travel time is specified at travel key level. For example, 15
• override: integer
  Minimum Value: -1

  Maximum Value: 999

  The override value for the travel time (in minutes) that needs to be set for the distance at travel key level. For example, 25

{
    "type":"object",
    "title":"Travel Key Override Data",
    "properties":{
        "distance":{
            "type":"integer",
            "minimum":-1,
            "maximum":999,
            "description":"The distance (in km) for which the override value of travel time is specified at travel key level. For example, 15"
        },
        "override":{
            "type":"integer",
            "minimum":-1,
            "maximum":999,
            "description":"The override value for the travel time (in minutes) that needs to be set for the distance at travel key level. For example, 25"
        }
    }
}

Back to Top

Response

Supported Media Types

• application/json
• application/schema+json

200 Response

This section describes the 200 status response for this operation.

Body ()

Root Schema : airlineDistanceBasedTravelPatchResponse

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"
        }
    }
}

409 Response

The API returns the HTTP 409 status code error with the description, 'Cannot override airline distance based travel time if Activity Travel Keys are detected automatically' if 'Detect activity travel keys automatically' is checked in Statistics configuration.

Default Response

This section describes the default error response for this operation.

Body ()

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"
    ]
}

Back to Top

Examples

The following example shows how to update airline distance based travel 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/airlineDistanceBasedTravel \
  -u '<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>' \
  -H 'content-type: application/json' \
  -d '{
	"items" : [ {
                "key" : "32771",
                "keyId": 4,
                "data" : [ {
                              "distance" : 10,
                              "override" : 25
                        }, {
                               "distance" : 50,
                              "override" : 53
                        } ]
                  } ]
    }

Response Header Example

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Mon, Wed, 02 Jun 2021 11:53:49 GMT
Content-Type: application/json; charset=utf-8

Response Body Example

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

Back to Top