Bulk update activities

post

/rest/ofscCore/v1/activities/custom-actions/bulkUpdate

This operation simultaneously creates or updates multiple activities in a single call.

This operation is used to synchronize data from an external system to Oracle Field Service Cloud. The operation performs the following actions:

  • Attempts to find an activity in Oracle Field Service Cloud based on the key fields provided in the request.
  • Creates a new activity, if no match is found or updates the existing activity, if a match is found.
  • Updates the related objects of an activity, if the objects are present in the request.
  • The following objects are updated:
    • Customer inventories
    • Required inventories
    • Resource preferences
    • Activity links

The updates are made in the order of the activity items in the request.

This operation is executed as multiple transactions where in each transaction may succeed or fail. The response contains a list of results which includes the success or failure of each transaction and the reason for failure (if applicable).

Restrictions:

The following restrictions apply while updating multiple activities simultaneously:

  • Maximum size of the decoded HTTP request is 5 MB.
  • File properties cannot be set.

Request

Body ()
Root Schema : Bulk Update Request
Type: object
Title: Bulk Update Request
The schema of the request body object for this operation.
Show Source
Nested Schema : Activities
Type: array
Title: Activities
The list of activity properties.
Show Source
Nested Schema : Bulk Update Parameters
Type: object
Title: Bulk Update Parameters
The parameters that determine the action to be performed on an existing activity in Oracle Field Service Cloud.
Show Source
  • Title: identifyActivityBy
    Allowed Values: [ "activityId", "apptNumber", "apptNumberPlusCustomerNumber" ]

    The logic used to identify the items in the 'activities' array.

    • If the value of the parameter is 'activityId', then each activity item in the 'activities' array has to contain an 'activityId' field.
      • If the 'activityId' field is specified, but activity with the same ID is not found in Oracle Field Service Cloud, then the 'Not found' error is returned for the activity item.
      • If an activity is found, then the existing activity is updated.
      • To make sure a new activity is created, you can set activityId to null.
    • If the value of the parameter is 'apptNumber', then each activity item in the 'activities' array has to contain an 'apptNumber' field.
      • If the 'apptNumber' field is specified, but activity with the same apptNumber is not found in Oracle Field Service Cloud, then a new activity is created with the specified apptNumber.
      • If an activity is found, then the existing activity is updated.
    • If the value of the parameter is 'apptNumberPlusCustomerNumber', then each activity item in the 'activities' array has to contain the 'apptNumber' and 'customerNumber' fields.
      • If both the fields are specified, but activity with the same apptNumber and customerNumber is not found in Oracle Field Service Cloud, then a new activity is created with the specified fields.
      • If an activity is found, then the existing activity is updated.
  • If Exists Then Do Not Update Fields
    Title: If Exists Then Do Not Update Fields
    The fields are not updated, if the activity already exists in Oracle Field Service Cloud.
  • Title: If In Final Status Then
    Allowed Values: [ "doNothing", "createNew", "updateExisting" ]
    The parameter specifies the action to be performed for an existing activity with the final status. Activity in a final status means that the activity exists in Oracle Field Service Cloud and can have one of the following statuses, 'completed', 'cancelled', 'notDone'.

    'doNothing' means that the API should not perform any actions when an activity is found with a final status.

    'createNew' means that the API should ignore the existing activity and create a new one, when an activity is found with a final status. 'The parameter cannot be set to 'createNew' when the 'identifyActivityBy' parameter is set to 'activityId'.

    'updateExisting' means that the API should update an existing activity, when an activity is found with a final status.

  • Title: Inventory Properties Update Mode
    Allowed Values: [ "keepProperties", "eraseProperties" ]

    The processing mode for updating the properties of each inventory item in the 'inventories' array. The possible values of this parameter are:

    • keepProperties: The specified inventory properties are updated and the properties that are not specified are retained.
    • eraseProperties: The specified inventory properties are replaced and the properties that are not specified are erased. This is the default value of the parameter.
Nested Schema : bulkUpdateActivityItemSchema
Type: object
Show Source
Match All
Show Source
Nested Schema : Customer Inventories
Type: object
Title: Customer Inventories
The collection of customer inventories assigned to the activity.
Show Source
Nested Schema : Linked Activities
Type: object
Title: Linked Activities
The array of linked activity objects which contain the link direction keys for the linked activity key fields and are defined in the identifyActivityBy and link type parameters.
Show Source
Nested Schema : Required Inventories of Activity
Type: object
Title: Required Inventories of Activity
The schema of the request body object for this operation.
Show Source
Nested Schema : Resource Preferences
Type: object
Title: Resource Preferences
The collection of resource preferences that can be assigned to an activity.
Show Source
Nested Schema : Activity Properties
Type: object
Title: Activity Properties
The properties of the specified 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.

    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 Type

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

    • The resources to which the activities can be assigned.
    • The activity processing details.
    • The interaction of the activity with different modules of Oracle Field Service Cloud.
  • 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 Cloud and may be left empty.
  • Title: City
    The city of the customer where the activity is scheduled. This field is used for geocoding and must contain a valid address.
  • Title: Country Code
    The code of the country where the activity is scheduled.
  • Title: Customer Cell
    The customer's cell phone number. From version 17.2.1, the phone number is saved in OFSC with the '+' symbol. For example, if you enter the phone number as +1(234)234-23_42, it is saved in OFSC as +12342342342. In versions before 17.2.1, the phone number is saved as 12342342342.
  • Title: Customer Email
    The email address of the customer.
  • Title: Customer Name
    The name of the customer.
  • Title: Customer Number
    The account number of the customer. This parameter 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 Cloud and can be left empty.
  • Title: Customer Phone
    The regular (land) phone number of the customer. From version 17.2.1, the phone number is saved in OFSC with the '+' symbol. For example, if you enter the phone number as +1(234)234-23_42, it is saved in OFSC as +12342342342. In versions before 17.2.1, the phone number is saved as 12342342342.
  • Title: Duration
    Minimum Value: 0
    Maximum Value: 65535
    Estimated activity duration in minutes. The duration specified in request will only be applied if the 'Calculate activity duration using statistics' checkbox is unchecked for the Activity Type of the activity being created/updated. This field is only used for regular activities. To change the length of the multi-day activities please use the field "multidayTimeToComplete" instead.
  • Title: Language
    The preferred language of the customer. This parameter is optional and its value defaults to the language set for the Login screen.

    The accepted language codes are 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: Segmentable Activity Status
    The status of the segmentable activity.
  • Title: Points
    Minimum Value: 0
    Maximum Value: 65535
    The cost of the activity in 'points'. This parameter is intended for use by the Routing module.
  • Title: Postal Code
    The postal code of the customer. This field is used for geocoding and must contain a valid address.
  • Title: Reminder Time
    The number of minutes before the activity start time the customer must be notified of the activity.
  • Title: Service Window End
    The time when the service window ends for the activity. The time is displayed in 'HH:MM:SS' format.

    If the activity type feature 'SLA and Service window use customer time zone' is enabled, then the service window is accepted in the time zone of the customer. If it is not enabled, then the Service Window is accepted in the time zone of the resource to which the activity is currently assigned.

    If the activity is later assigned to another resource and the activity type feature 'SLA and Service window use customer time zone' is enabled, then the Service Window is recalculated so that the fields are not changed in the customer's time zone, but they are changed in the time zone of the new resource.

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

    If the activity type feature 'SLA and Service window use customer time zone' is enabled, then the service window is accepted in the time zone of the customer. If it is not enabled, then the Service Window is accepted in the time zone of the resource to which the activity is currently assigned.

    If the activity is later assigned to another resource and the activity type feature 'SLA and Service window use customer time zone' is enabled, then the Service Window is recalculated so that the fields are not changed in the customer's time zone, but they are changed in the time zone of the new resource.

  • Set Position in Route
    Title: Set Position in Route
    The value of this element determines the position of the activity in the route. If this element is present then activity will be put to specified position in route. The parameter is optional, if it is absent then the value "position: byServiceWindow" is used.
  • Set Travel Time
    Title: Set Travel Time
    The objects used to set the travel time of the activity. The travel time is set only if the specified previousActivity/previousActivityId is ordered before the activity for which the travel time is set.
  • 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.

    If the activity type feature 'SLA and Service window use customer time zone' is enabled, then the SLA is accepted in the time zone of the customer. If it is not enabled, then the SLA is accepted in the time zone of the resource to which the activity is currently assigned.

    If the activity is later assigned to another resource and the activity type feature 'SLA and Service window use customer time zone' is enabled, then the SLA is recalculated so that the fields are not changed in the customer's time zone, but they are changed in the time zone of the new resource.

  • 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.

    If the activity type feature 'SLA and Service window use customer time zone' is enabled, then the SLA is accepted in the time zone of the customer. If it is not enabled, then the SLA is accepted in the time zone of the resource to which the activity is currently assigned.

    If the activity is later assigned to another resource and the activity type feature 'SLA and Service window use customer time zone' is enabled, then the SLA is recalculated so that the fields are not changed in the customer's time zone, but they are changed in the time zone of the new resource.

  • Title: State Province
    The state or province of the customer. This field is used for geocoding and must contain a valid address.
  • Title: Status
    Allowed Values: [ "cancelled", "completed", "suspended", "started", "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.
  • Title: Team Resource ID
    The identifier of the team resource for a teamwork activity.
  • 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. 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. This parameter accepts both OFSC time zone names (for example, Eastern) and IANA standard time zone names (for example, America/New_York). It is recommended that you specify IANA names. For a list of supported time zones, see Supported Time Zones.

    This parameter is optional and defaults to the time zone of the resource to which the activity is assigned.

    Zones.

Nested Schema : items
Type: array
Show Source
  • Inventory
    Title: Inventory
    The inventory that is installed or deinstalled at the customer's site during an activity.
Nested Schema : Inventory
Type: object
Title: Inventory
The inventory that is installed or deinstalled at the customer's site during an activity.
Show Source
Nested Schema : Items
Type: array
Title: Items
The list of linked activity objects for the linked activity key fields.
Show Source
Nested Schema : items
Type: object
Show Source
Nested Schema : Activity Link
Type: object
Title: Activity Link
The link between the activity key fields and the link properties.
Show Source
Nested Schema : Items
Type: array
Title: Items
The collection of required inventories for the specified activity.
Show Source
Nested Schema : Required Inventory
Type: object
Title: Required Inventory
The array of required inventory item objects assigned to the specified activity.
Show Source
  • Title: Required Inventory Type
    The required inventory type for the specified activity.
  • Title: Required Inventory Model
    The required inventory model for the specified activity.
  • Title: Required Inventory Quantity
    The required quantity of inventory for the specified activity.
Nested Schema : Items
Type: array
Title: Items
The array of required preferences for the specified activity.
Show Source
Nested Schema : Resource Preference
Type: object
Title: Resource Preference
The resource preference of an activity.
Show Source
  • Title: Preference Type
    Allowed Values: [ "required", "preferred", "forbidden" ]
    The type of resource preference for the activity.
    • preferred - the resource is preferred while routing.
    • required - the activity can only be assigned to a required resource.
    • forbidden - the activity cannot be assigned to the specified resource.
  • Title: Resource ID
    The unique identifier of the resource in Oracle Field Service Cloud.
Nested Schema : Set Position in Route
Type: object
Title: Set Position in Route
The value of this element determines the position of the activity in the route. If this element is present then activity will be put to specified position in route. The parameter is optional, if it is absent then the value "position: byServiceWindow" is used.
Show Source
  • Title: Activity ID
    The unique identifier of the activity in Oracle Field Service Cloud. If the value of the parameter 'position' is 'afterActivity', then the other activity is scheduled after this activity.
  • Title: Position
    Allowed Values: [ "first", "last", "notOrdered", "byServiceWindow", "afterActivity" ]
    The position of the activity in the route.
Nested Schema : Set Travel Time
Type: object
Title: Set Travel Time
The objects used to set the travel time of the activity. The travel time is set only if the specified previousActivity/previousActivityId is ordered before the activity for which the travel time is set.
Show Source
  • Title: Position
    Allowed Values: [ "first", "afterActivity" ]
    The expected position of the activity in a route.

    To adjust the travel time of an activity, specify the location from where the travel is starting. The location can be the start of the route or another activity. This information is used when activities are reordered or moved while performing a sequence of operations.

  • Previous Activity
    Title: Previous Activity
    The objects in this array are used instead of the 'previousActivityId' parameter to find activities when internal IDs cannot be used. For example, it is used for the bulkUpdate operation.

    The 'previousActivity' activity array contains two items: 'apptNumber' and 'customerNumber'. The parameter 'apptNumber' is mandatory. The parameter 'customerNumber' is only required when the 'bulkUpdate/identifyActivityBy' option is set to 'apptNumberPlusCustomerNumber'.

    The operation returns an error if the system is unable to find any activity using the specified 'apptNumber' and 'customerNumber' values.

  • Title: Previous Activity ID
    The identifier of a previous activity that requires travel time calculation.

    If an activity doesn't require traveling (for example, calling your manager), then the identifier of the activity cannot be used as the 'Travel previous activity ID'. In such case, it is assigned to an ID of a previous activity that required travel.

    This parameter is mandatory when the value of the parameter 'position' is 'afterActivity'.

    Note: The operation does not return any error if the adjustment cannot be made because the specified 'previousActivityId' doesn't correspond to a real-time activity. This can be detected by verifying the 'travelTime' value returned.

  • Title: Source
    Allowed Values: [ "manual", "external" ]
    The origin of the travel time data. The following are the allowed values:
    • manual - indicates that the travel time value is entered manually by a user.
    • external - indicates that the travel time value is estimated based on the statistics or street-level routing service results.
  • Title: Travel Time
    Minimum Value: 0
    Maximum Value: 65535
    The travel time for the specified activity.
Nested Schema : Previous Activity
Type: object
Title: Previous Activity
The objects in this array are used instead of the 'previousActivityId' parameter to find activities when internal IDs cannot be used. For example, it is used for the bulkUpdate operation.

The 'previousActivity' activity array contains two items: 'apptNumber' and 'customerNumber'. The parameter 'apptNumber' is mandatory. The parameter 'customerNumber' is only required when the 'bulkUpdate/identifyActivityBy' option is set to 'apptNumberPlusCustomerNumber'.

The operation returns an error if the system is unable to find any activity using the specified 'apptNumber' and 'customerNumber' values.

Show Source
Nested Schema : If Exists Then Do Not Update Fields
Type: array
Title: If Exists Then Do Not Update Fields
The fields are not updated, if the activity already exists in Oracle Field Service Cloud.
Show Source
  • Title: Property Name
    The activity property name that need not be updated.
Back to Top

Response

Supported Media Types

200 Response

This section describes the 200 status response for this operation.
Body ()
Root Schema : Bulk update response
Type: object
Title: Bulk update response
The schema of the response body object for this operation.
Show Source
Nested Schema : Results
Type: array
Title: Results
The list of results in the order of the activity items in the request.
Show Source
Nested Schema : Result
Type: object
Title: Result
The result item of the Bulk Update operation.
Show Source
Nested Schema : Activity Keys
Type: object
Title: Activity Keys
The activity key fields used to create or update the activity. If the key fields are not known, then the list is not returned. For example, the Bulk Update operation is not successful, if a key field is not specified.
Show Source
  • Title: Activity ID
    The unique identifier of the activity in Oracle Field Service Cloud.
  • 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 Cloud and can be left empty.
  • 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 Cloud and can be left empty.
Nested Schema : Errors
Type: array
Title: Errors
The list of errors that occurred during the Bulk Update operation.
Show Source
Nested Schema : Operations Failed
Type: array
Title: Operations Failed
The failed operations during the Bulk Update operation.
Show Source
Nested Schema : Operations Performed
Type: array
Title: Operations Performed
The successful operations during the Bulk Update operation.
Show Source
Nested Schema : Error
Type: object
Title: Error
An object containing details of the specific failed operation.
Show Source

Default Response

This section describes the default error response for this operation.
Body ()
Root Schema : Error
Type: object
Error response
Show Source
Back to Top

Examples

The following example shows how to bulk update activities by submitting a POST request on the REST resource using cURL.

Note:

This request creates a new activity with apptNumber="XS3453456" if it doesn't exist. If the activity with apptNumber "XS3453456" exists in the system it will be updated, unless it is in the status 'Completed' (which means no changes will be performed according to the "ifInFinalStatusThen": "doNothing" option).

The request also updates the activity with the list of customer inventories (in the Inventories section), list of required inventories for that activity ("requiredInventories" section), creates links to other activities ("linkedActivities" section), and updates resource preference information ("resourcePreferences" section).

In this example, the "linkedActivities" section describes relations of the activity "XS3453456" with the activities, "A0001" and "B0002". The resulting relation will be as follows:
  • for the "fromActivity" item: A link is created from the activity "A0001" to the activity "XS3453456" with the link type "start-after". This indicates that the activity "XS3453456" should be started after the activity "A0001".
  • for the "toActivity" item: A link is created from the activity "XS3453456" to an activity "B0002" with the link type "start-after". This indicates that the activity "B0002" should be started after the activity "XS3453456".
curl -X 'POST' \
     -u '<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>' \
     -H 'Content-Type: application/json' \
     --data-binary '{
    "updateParameters": {
        "identifyActivityBy": "apptNumber",
        "ifInFinalStatusThen": "doNothing"
    },
    "activities": [
        {
            "apptNumber": "XS3453456",
            "resourceId": "33011",
            "date": "2017-06-09",
            "activityType": "9",
            "timeZone": "America/New_York",
            "language": "en-US",
            "inventories": {
                "items": [
                    {
                        "inventoryType": "RG6BLK",
                        "inventory_model": "Z222",
                        "quantity": 10
                    },
                    {
                        "inventoryType": "RG6BLK",
                        "inventory_model": "X333",
                        "quantity": 5
                    }
                ]
            },
            "requiredInventories": {
                "items": [
                    {
                        "inventoryType": "NS",
                        "model": "A22",
                        "quantity": 10
                    },
                    {
                        "inventoryType": "NS",
                        "model": "B22",
                        "quantity": 10
                    }
                ]
            },
            "linkedActivities": {
                "items": [
                    {
                        "fromActivity": {
                            "apptNumber": "A0001",
                            "linkType": "start-after"
                        }
                    },
                    {
                        "toActivity": {
                            "apptNumber": "B0002",
                            "linkType": "start-after"
                        }
                    }
                ]
            },
            "resourcePreferences": {
                "items": [
                    {
                        "resourceId": "testActivityCustomAcQYNWZCUYYP",
                        "preferenceType": "preferred"
                    },
                    {
                        "resourceId": "testActivityCustomAcCKIVJZFSSB",
                        "preferenceType": "preferred"
                    }
                ]
            }
        }
    ]
}'
https://<instance_name>.etadirect.com/rest/ofscCore/v1/activities/custom-actions/bulkUpdate'

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:36 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.

{
    "results": [
        {
            "operationsPerformed": [
                "updateProperties"
            ],
            "activityKeys": {
                "activityId": 4225270,
                "apptNumber": "testApptNumber",
                "customerNumber": ""
            }
        }
    ],
    "links": [
        {
            "rel": "canonical",
            "href": "https://<instance_name>.etadirect.com/rest/ofscCore//v1/activities/custom-actions/bulkUpdate"
        }
    ]
}
Back to Top