1. REST API for Oracle Field Service Cloud Service
  2. Tasks
  3. Core
  4. Activities
  5. Activity Actions

Cancel an activity

post

/rest/ofscCore/v1/activities/{activityId}/custom-actions/cancel

This operation updates the status of the specified activity from 'pending' or 'en route' to 'cancelled'.

The operation is successful only if the following conditions are met:

  • The status of the specified activity is 'pending' or 'en route'.
  • The activity is not scheduled for a past date.

Request

Path Parameters
Body ()
Root Schema : Custom Action Activity Status Change Schema
Type: object
Title: Custom Action Activity Status Change Schema
The schema of the request body object for this operation.
Show Source
  • Title: Segmentable Activity Status
    Allowed Values: [ "cancelled", "completed", "notdone" ]
    The status of the segmentable activity. If a value is specified for this parameter while updating an individual segment, then the status of the segmentable activity is changed to the specified value. This parameter is generally used to complete a segmentable activity.
  • Title: Segmentable Activity Duration
    Minimum Value: 0
    The duration of the segmentable activity. If the value of this parameter is specified when updating an individual segment, then the duration of the segmentable activity is changed to the specified value. If the value of this parameter is set to zero, then the segmentable activity ends. Maximum value is 599995.
  • Title: Time of Operation
    The time when the action is registered. Specify the time in 'YYYY-MM-DD HH:MM:SS' format. The time must be in the time zone of the resource to which the activity is assigned. The default value is the current time. Note that the time of a custom action cannot be less then the time of the previous action. (e.g. activity cannot be suspended earlier then when it was started etc.)
Back to Top

Response

Supported Media Types

200 Response

Body ()
Root Schema : Activity Properties
Type: object
Title: Activity Properties
The properties of the activity.
Show Source
  • Title: Access Schedule
    The schedule (that is, the set of time intervals or access hours, two intervals per week day) when the asset or the activity location is accessible. Work must start and complete during this interval. It is generally not possible to work beyond the access hours. Maximum field length is 1020.

    Access Schedule Field Format
    This field is a string, which contains an inner json object (encoded as a string). For example, "accessSchedule": "{\"schedule\":[{\"daysOfWeek\":[\"Mon\",\"Tue\"],\"hours\":[[\"07:00\",\"12:00\"]]}]}"

    The inner json object has the following schema:

    {
    "type": "object",
    "properties": {
    "schedule": {
    "type": "array",
    "items": {
    "type": "object",
    "properties": {
    "daysOfWeek": {
    "type": "array",
    "items": {
    "type": "string",
    "enum": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ]
    }
    },
    "hours": {
    "type": "array",
    "items": {
    "type": "array",
    "items": { "type": "string" }
    }
    }
    }
    }
    },
    "exceptDates": {
    "type": "array",
    "items": { "type": "string" }
    }
    }
    }

  • Title: Activity Flow
    Activity flow label
  • Title: Activity ID
    The unique identifier of the activity in Oracle Field Service.
  • Title: Activity Type

    The label of the activity type. Based on the activity type, predefined company-specific rules are applied when processing an activity. Predefined company-specific rules cover the following:

    • The resources that the activity can be assigned to.
    • The activity processing details.
    • The interaction of the activity with different modules of Oracle Field Service.
  • Title: Appt Number
    This field may be used by integrations to store the identifier of the activity in the origin system. This field has no business significance in Oracle Field Service and can be left empty. Maximum field length is 40.
  • Title: Auto Routed To Date
    The date to which the activity was moved automatically by routing. Rescheduling the activity does not change this value. It is a read-only field.
  • Title: Auto Routed To Resource
    The external ID of resource to which the activity was last assigned by routing. Reassigning the activity does not change this value. It is a read-only field. If the field has no value, it means that the routing assigned the activity to a resource with empty external ID.
  • Title: City
    The city of the customer where the activity is scheduled. Maximum field length is 60.
  • Title: Coordinate Accuracy
    The coordinate accuracy of the activity. It is a read-only field. The following values are returned:

    • Low
    • Medium
    • High

  • Title: Country Code
    The code of the country where the activity is scheduled.
  • Title: Customer Cell
    The cell phone number of the customer. From version 17.2.1, the phone number is saved in Oracle Field Service with the '+' symbol. For example, if you enter the phone number as +1(234)234-23_42, it is saved in Oracle Field Service as +12342342342. In versions before 17.2.1, the phone number is saved as 12342342342. Maximum field length is 240.
  • Title: Customer Email
    The email address of the customer. Maximum field length is 320.
  • Title: Customer Name
    The name of the customer. Maximum field length is 420.
  • Title: Customer Number
    The account number of the customer. This field is used by integrations as a placeholder for the external identifier of the Account ID in the application. This parameter has no business significance in Oracle Field Service and can be left empty. Maximum field length is 40.
  • Title: Customer Phone
    The regular (land) phone number of the customer. From version 17.2.1, the phone number is saved in Oracle Field Service with the '+' symbol. For example, if you enter the phone number as +1(234)234-23_42, it is saved in Oracle Field Service as +12342342342. In versions before 17.2.1, the phone number is saved as 12342342342. Maximum field length is 240.
  • Title: Date
    The date on which the activity is scheduled. This field is not present in the response, if the activity is not scheduled for any particular date.
  • Title: Delivery Window End
    The time when the activity delivery window ends. The time is displayed in the time zone of the resource to which the activity is assigned, and is in 'HH:MM:SS' format.
  • Title: Delivery Window Start
    The time when the activity delivery window starts. The time is displayed in the time zone of the resource to which the activity is assigned, and is in HH:MM:SS format.
  • Title: Duration
    The estimated duration of the activity in minutes.
  • Title: End Time
    The predicted or the actual end time of the activity. The time is displayed in the time zone of the resource to which the activity is assigned, and is in 'YYYY-MM-DD HH:MM:SS' format.
  • Title: First Manual Operation
    The name of the first manual operation on the activity.
  • Title: First Manual Operation User
    The user who performed the first manual operation on the activity.
  • Title: Language
    The preferred language of the customer. This parameter returns two-character code (e.g. "en") in API responses. To obtain ISO code of the language (e.g. "en-US") read the "languageISO" parameter. In the requests this parameter accepts both formats (e.g. "en" or "en-US"). It is recommended to use ISO format. The language codes listed on: Supported Language Codes.
  • Title: Language ISO
    The preferred language of the customer. This parameter is only present in the responses and will be ignored if it is present in a request. To update language use the parameter "language". The language codes listed on: Supported Language Codes.
  • Title: Latitude
    Minimum Value: -90
    Maximum Value: 90
    The geographic coordinates that specify the location of the activity.
  • Title: Longitude
    Minimum Value: -180
    Maximum Value: 180
    The geographic coordinates that specify the location of the activity.
  • Title: Master Activity ID
    The identifier of a segmentable activity. It is available for activities that are segments of a segmentable activity which has the recordType=multiday_activity_segment. This field is not set for regular activities.
  • Title: Points
    Minimum Value: 0
    Maximum Value: 65535
    The cost of the activity in 'points'. This field is intended for use by the Routing module.
  • Title: Position In Route
    The position of the activity in the route. For not-ordered activities, this field is not present in the response. For ordered activities, a 1-based number is returned.
  • Title: Postal Code
    The postal code of the customer. This field is used for geocoding and must contain a valid address. Maximum field length is 60.
  • Title: Record Type
    Allowed Values: [ "regular", "reopened", "prework", "multiday_activity", "multiday_activity_segment" ]

    The type of the activity record. The following values are allowed:

    • regular - this is the default record type for most new activities.
    • prework - this type of record is created if a technician has to perform some work before the actual activity starts.
    • reopened - this type of record is created when an activity is reopened for some reason.
    • multiday_activity - this record type is created when the 'activityType' indicates that this is a segmentable activity.
    • multiday_activity_segment - a number of these record types are created for segmentable activities, based on their duration and time slot settings.
  • Title: Reminder Time
    The number of minutes before the activity start time the customer must be notified of the activity.
  • Title: Resource ID

    The identifier of the resource to which this activity is assigned. This field is not returned if the resource ID is empty.

    Note: Do not use empty strings in requests.

  • Title: Resource Time Zone
    The time zone of the resource to which this activity is assigned (for example, Eastern).

    This is a read-only field and may change when the activity is reassigned to another resource.

  • Title: Resource Time Zone Diff
    The difference between UTC and the resource's local time, displayed in minutes. For example, -180 means that the resource time is 3 hours behind UTC.

    This field is read-only and may change when the activity is reassigned to another resource.

  • Title: Resource Time Zone IANA name
    The IANA name of the resource's time zone (For example, America/New_York).

    This field is read-only and may change when the activity is reassigned to another resource.

  • Title: Service Window End
    The time when the service window ends for the activity. The time is displayed in 'HH:MM:SS' format.

    Service window is returned in the time zone of the resource to which the activity is currently assigned.

  • Title: Service Window Start
    The time when the service window starts for the activity. The time is displayed in 'HH:MM:SS' format.

    Service window is returned in the time zone of the resource to which the activity is currently assigned.

  • Title: Sla Window End
    The time when the service level agreement (SLA) window ends. The time is displayed in 'YYYY-MM-DD HH:MM:SS' format.

    SLA window is returned in the time zone of the resource to which the activity is currently assigned.

  • Title: Sla Window Start
    The time when the service level agreement (SLA) window starts. The time is displayed in 'YYYY-MM-DD HH:MM:SS' format.

    SLA window is returned in the time zone of the resource to which the activity is currently assigned.

  • Title: Start Time
    The estimated time of arrival for the activities in 'pending' status, and the actual start time for the activities in 'started' and 'completed' status. The time is displayed in 'YYYY-MM-DD HH:MM:SS' format, in the time zone of the resource to which the activity is assigned.
  • Title: State Province
    The state or province of the customer. This field is used for geocoding and must contain a valid address. Maximum field length is 60.
  • Title: Status
    Allowed Values: [ "cancelled", "completed", "suspended", "started", "enroute", "pending", "notdone" ]

    The status of the activity. As a technician works through the activity, the status changes. The actions that are available for an activity are based on this status.

    A newly created activity has the status as 'pending', it can then be changed to 'cancelled' or 'started'. The status of an activity can be changed to 'complete', 'notdone', or 'suspended' only if it has the status as 'started'.

  • Title: Street Address
    The street address of the customer. This field is used for geocoding and must contain a valid address. Maximum field length is 240.
  • Title: Team Resource ID
    The identifier of the team resource for a teamwork activity.
  • Title: Time Delivered End
    The end time of the technician's arrival interval as communicated to the customer. The value is used by routing optimization engine to reduce changes to arrival time, so it is important to keep the value actual. This time is displayed in 'YYYY-MM-DD HH:MM:SS' format in the time zone of the resource to which the activity is assigned.
  • Title: Time Delivered Start
    The start time of the technician's arrival interval as communicated to the customer. The value is used by routing optimization engine to reduce changes to arrival time, so it is important to keep the value actual. This time is displayed in 'YYYY-MM-DD HH:MM:SS' format in the time zone of the resource to which the activity is assigned.
  • Title: Time Of Assignment
    The time when the activity is assigned to the technician. This time is displayed in the time zone of the resource to which the activity is assigned.
  • Title: Time Of Booking
    The time when the customer booked the activity. The time is displayed in the time zone of the customer.
  • Title: Time Slot
    The time slot during which the activity is completed. The time slot also indicates the service window for the activity. This time is displayed in the time zone of the resource to which the activity is assigned.
  • Title: Time Zone
    The name of the customer's time zone. For example, Eastern.

    For a list of supported time zones, see Supported Time Zones.

  • Title: Time Zone IANA Name

    The IANA name of the time zone. (https://www.iana.org/time-zones). For example, America/New_York.

    This field is read-only, but when creating or updating an activity, the field 'timeZone' accepts both IANA names and Oracle Field Service specific names.

  • Title: Travel Estimation Method
    The travel estimation method. It is a read-only field. The following values are returned:

    • Airline Distance
    • Airline Distance and Statistics
    • External Adjustment
    • Manual Adjustment
    • Not Estimated
    • Point to Point
    • Same Location
    • Statistics
    • Street Level Routing
    • Travel key based Airline Distance
    • Using Defaults

  • Title: Travel Time

    The estimated time taken to travel to this activity. For activities that were started (status is 'started', 'completed', 'notdone') this parameter indicates reported travelling time, which is calculated based on the actual times.

    Notice that reported travelling time keeps the paid part of the travelling time and may be different from the value shown in UI, depending on the "Travel Allowance" configuration of resource type.

    (Exception : the "activityChanges" object of activity events always brings the full value of the travelling time).

  • Title: Work Zone
    The work zone in which the activity occurs. It is a read-only field that is automatically assigned to an activity, based on the company setting 'work zone key' and the activity properties. For example, if 'work zone key' is the first 4 symbols of the 'city' field, then the activity with city='Belfast' will have a work zone assigned which has 'BELF' as one of its keys.

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 cancel activity by submitting a POST request on the REST resource using cURL.

curl -X 'POST' \
     -H 'Content-Type: application/json' \
     --data-binary '{}' \
     'https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/4225271/custom-actions/cancel'

Example of Response Header

The following shows an example of the response header.

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Fri, 18 Mar 2016 02:26:38 GMT
Content-Type: application/json; charset=utf-8
Connection: close

Example of Response Body

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

{
    "activityId": 4225271,
    "resourceId": "33011",
    "date": "2016-03-18",
    "apptNumber": "testApptNumberNew",
    "recordType": "regular",
    "status": "cancelled",
    "activityType": "7",
    "language": "en",
    "timeZone": "Arizona",
    "timeZoneIANA": "America/Phoenix",
    "deliveryWindowStart": "09:00:00",
    "deliveryWindowEnd": "10:00:00",
    "timeOfBooking": "2016-03-17 22:26:38",
    "timeOfAssignment": "2016-03-17 22:26:38",
    "requiredInventories": {
        "links": [
            {
                "rel": "canonical",
                "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore//v1/activities/4225271/requiredInventories"
            }
        ]
    },
    "linkedActivities": {
        "links": [
            {
                "rel": "canonical",
                "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore//v1/activities/4225271/linkedActivities"
            }
        ]
    },
    "resourcePreferences": {
        "links": [
            {
                "rel": "canonical",
                "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore//v1/activities/4225271/resourcePreferences"
            }
        ]
    },
    "workSkills": {
        "links": [
            {
                "rel": "canonical",
                "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore//v1/activities/4225271/workSkills"
            }
        ]
    },
    "links": [
        {
            "rel": "canonical",
            "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore//v1/activities/4225271"
        },
        {
            "rel": "describedby",
            "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore//v1/metadata-catalog/activities"
        },
        {
            "rel": "route",
            "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore//v1/resources/33011/routes/2016-03-18"
        }
    ]
}
Back to Top