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

Create new activity

post

/rest/ofscCore/v1/activities

This operation creates a new activity. By default, the new activity has status set to 'pending'.

This operation is a create-only operation. If the operation is used after the initial activity is created with the same request body, a new activity with the same information is created.

Request

Body ()
New activity properties
Root Schema : createActivitySchema
New activity properties
Match All
Show Source
Nested Schema : New activity properties
Type: object
Title: New activity properties
Activity properties
Show Source
  • Title: Access Schedule
    Access Schedule defines the schedule (i.e. the set of time intervals/access hours, two intervals per week day) when the asset or the activity location is accessible. Work should be started and finished during the same Access Schedule interval. Performing the work beyond Access Hours is generally not possible.

    Access Schedule field format
    This field is a string, which contains an inner json object (encoded as a string). e.g. "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
    An activity type corresponds to a predefined company-specific set of rules applied when processing an activity. The rules cover the resources the activity can be assigned to, details of its processing and interaction with different modules of Oracle Field Service Cloud
  • Title: Appt Number
    This field is usually used by integrations to hold the external Id of activity - Id in the origin system.Has no business logic in Oracle Field Service Cloud and can be left empty.
  • Title: City
    customer's address. Note: this field is used by geocoding and, therefore, must contain a valid address. Other values will not be resolved correctly by the geocoding server.
  • Title: Country code
    Country code
  • Title: Customer Cell
    customer's cell phone number
  • Title: Customer Email
    customer's email address
  • Title: Customer Name
    customer's name.
  • Title: Customer Number
    customer's account number. This field is usually used by integrations to hold the external Id of Account - Id in the origin system. Has no business logic in Oracle Field Service Cloud and can be left empty.
  • Title: Customer Phone
    customer's regular (land) phone number
  • Title: Date
    Date this activity is scheduled. This field can be absent, meaning the activity is not scheduled for any particular date
  • Title: Delivery Window End
    activity delivery window end time in HH:MM:SS format
  • Title: Delivery Window Start
    activity delivery window start time in HH:MM:SS format
  • 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.
  • Title: Language
    Customer's preferred language

    This field is optional, and defaults to the language that is set to be used for the Login screen. When setting this field, the following language codes are accepted: Supported Language Codes.

  • Title: Latitude
    Minimum Value: -90
    Maximum Value: 90
    activity coordinates
  • Title: Longitude
    Minimum Value: -180
    Maximum Value: 180
    activity coordinates
  • Title: Points
    Minimum Value: 0
    Maximum Value: 65535
    Activity cost in "points". This field is intended for use by Routing module
  • Title: Postal Code
    customer's postal code. Note: this field is used by geocoding and, therefore, must contain a valid address. Other values will not be resolved correctly by the geocoding server.
  • Title: Reminder Time
    Reminder notification time. How many minutes before the activity start time the customer should be notified
  • Title: Resource Id
    Id of the resource this activity is assigned to.
  • Title: Service Window End
    Service window end time in "HH:MM:SS" format.

    If activity type configured with parameter 'SLA and Service window use customer time zone' then Service Window is accepted in the time zone of customer (field 'timeZone'), otherwise Service Window is accepted in the time zone of the resource to which this activity is assigned

    Note that if the activity is later moved to another resource, and has activity type feature 'SLA and Service window use customer time zone' enabled, then Service Window will be recalculated, so that in the customer's time zone these fields remain unchanged, but appear changed in the time zone of the new resource.

  • Title: Service Window Start
    Service window start time in "HH:MM:SS" format.

    If activity type configured with parameter 'SLA and Service window use customer time zone' then Service Window is accepted in the time zone of customer (field 'timeZone'), otherwise Service Window is accepted in the time zone of the resource to which this activity is assigned

    Note that if the activity is later moved to another resource, and has activity type feature 'SLA and Service window use customer time zone' enabled, then Service Window will be recalculated, so that in the customer's time zone these fields remain unchanged, but appear changed in the time zone of the new resource.

  • Set Position in Route
    Title: Set Position in Route
    If this element is present then activity will be put to specified position in route
  • Set travel time
    Title: Set travel time
    If this element is present then it will attempt to set activity's travelTime. The travel time will only be set if the specified previousActivity/previousActivityId is actually ordered before the activity you are setting travelTime for.
  • Title: Sla Window End
    SLA end time in "YYYY-MM-DD HH:MM:SS" format.

    If activity type configured with parameter 'SLA and Service window use customer time zone' then SLA is accepted in the time zone of customer (field 'timeZone'), otherwise SLA is accepted in the time zone of the resource to which this activity is assigned

    Note that if the activity is later moved to another resource, and has activity type feature 'SLA and Service window use customer time zone' enabled, then SLA will be recalculated, so that in the customer's time zone these fields remain unchanged, but appear changed in the time zone of the new resource.

  • Title: Sla Window Start
    SLA start time in "YYYY-MM-DD HH:MM:SS" format.

    If activity type configured with parameter 'SLA and Service window use customer time zone' then SLA is accepted in the time zone of customer (field 'timeZone'), otherwise SLA is accepted in the time zone of the resource to which this activity is assigned

    Note that if the activity is later moved to another resource, and has activity type feature 'SLA and Service window use customer time zone' enabled, then SLA will be recalculated, so that in the customer's time zone these fields remain unchanged, but appear changed in the time zone of the new resource.

  • Title: State Province
    customer's state / province. Note: this field is used by geocoding and, therefore, must contain a valid address. Other values will not be resolved correctly by the geocoding server.
  • Title: Street Address
    customer's address. Note: this field is used by geocoding and, therefore, must contain a valid address. Other values will not be resolved correctly by the geocoding server.
  • Title: Team Resource Id
    Id of the team resource if this activity is a team work
  • Title: Time Delivered End
    An arrival interval end time as communicated to the end customer
  • Title: Time Delivered Start
    An arrival interval start time as communicated to the end customer
  • Title: Time Of Assignment
    Time of assignment
  • Title: Time Of Booking
    Time of booking
  • Title: Time Slot
    Activity Time Slot. It defines the service window
  • Title: Time Zone
    Customer's time zone name.

    Note that this field accepts both OFSC time zone names (e.g. "Eastern") and IANA standard zone names (e.g. "America/New_York"). It is recommended that IANA names are used.

    This field is optional, and defaults to the time zone of the resource the activity is created on.

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

Nested Schema : Set Position in Route
Type: object
Title: Set Position in Route
If this element is present then activity will be put to specified position in route
Show Source
  • Title: activityId
    If "position" is "afterActivity" then this is the activityId after which the other activity will be put
  • Title: position
    Allowed Values: [ "first", "last", "notOrdered", "byServiceWindow", "afterActivity" ]
    position in route
Nested Schema : Set travel time
Type: object
Title: Set travel time
If this element is present then it will attempt to set activity's travelTime. The travel time will only be set if the specified previousActivity/previousActivityId is actually ordered before the activity you are setting travelTime for.
Show Source
  • Title: Position
    Allowed Values: [ "first", "afterActivity" ]
    Expected position of the activity in a route

    In order to adjust a travel time to a given activity, it is also necessary to specify a location this travel is expected to be started from. This location can be a start of the route or another activity.

    This information is mainly used to handle situations when activities are reordered or moved during performing a sequence of operations.

  • previousActivity
    Title: previousActivity
    This field can be used as a replacement to the 'previousActivityId' one when it is impossible to use internal IDs.

    Mainly, it is expected to be used for the 'bulkUpdate' command that doesn't use internal IDs. But, the 'previousActivityId' option also works in this case.

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

    Please note that the function returns an error when the system is unable to find any activity using the specified 'apptNumber' and 'customerNumber' values.

  • Title: previousActivityId
    It is an ID a previous activity that requires a calculation of travel time (has the 'Calculate travel' feature). If there is an activity that doesn't require traveling (for example: Call to manager), ID of this activity cannot be not used as 'Travel previous activity ID'. In this case, it is assigned to an ID of a previous activity that has a requires traveling.

    This field (or 'previousActivity') becomes mandatory when the 'position' is set to 'afterActivity'.

    Please note that the function doesn't return an error when the adjustment cannot be performed because the specified 'previousActivityId' doesn't correspond to an actual situation. This situation can be detected by checking a returned 'travelTime' value.

  • Title: Source
    Allowed Values: [ "manual", "external" ]
    Origin of the provided travel time data

    The 'manual' option is expected to be used when the adjustment value is entered by a human.

    The 'external' one corresponds to the case when the travel time value is estimated based on statistics or street-level routing service results.

  • Title: Travel time
    Minimum Value: 0
    Maximum Value: 65535
    Travel time to the specified activity
Nested Schema : previousActivity
Type: object
Title: previousActivity
This field can be used as a replacement to the 'previousActivityId' one when it is impossible to use internal IDs.

Mainly, it is expected to be used for the 'bulkUpdate' command that doesn't use internal IDs. But, the 'previousActivityId' option also works in this case.

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

Please note that the function returns an error when the system is unable to find any activity using the specified 'apptNumber' and 'customerNumber' values.

Show Source

Response

Supported Media Types

201 Response

Body ()
Root Schema : Activity properties
Type: object
Title: Activity properties
Activity properties
Show Source
  • Title: Access Schedule
    Access Schedule defines the schedule (i.e. the set of time intervals/access hours, two intervals per week day) when the asset or the activity location is accessible. Work should be started and finished during the same Access Schedule interval. Performing the work beyond Access Hours is generally not possible.

    Access Schedule field format
    This field is a string, which contains an inner json object (encoded as a string). e.g. "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 Id
    Unique identifier of activity in Oracle Field Service Cloud
  • Title: Activity Type
    An activity type corresponds to a predefined company-specific set of rules applied when processing an activity. The rules cover the resources the activity can be assigned to, details of its processing and interaction with different modules of Oracle Field Service Cloud
  • Title: Appt Number
    This field is usually used by integrations to hold the external Id of activity - Id in the origin system.Has no business logic in Oracle Field Service Cloud and can be left empty.
  • Title: City
    customer's address. Note: this field is used by geocoding and, therefore, must contain a valid address. Other values will not be resolved correctly by the geocoding server.
  • Title: Country code
    Country code
  • Title: Customer Cell
    customer's cell phone number
  • Title: Customer Email
    customer's email address
  • Title: Customer Name
    customer's name.
  • Title: Customer Number
    customer's account number. This field is usually used by integrations to hold the external Id of Account - Id in the origin system. Has no business logic in Oracle Field Service Cloud and can be left empty.
  • Title: Customer Phone
    customer's regular (land) phone number
  • Title: Date
    Date this activity is scheduled. This field can be absent, meaning the activity is not scheduled for any particular date
  • Title: Delivery Window End
    activity delivery window end time in HH:MM:SS format
  • Title: Delivery Window Start
    activity delivery window start time in HH:MM:SS format
  • Title: Duration
    Minimum Value: 0
    Maximum Value: 65535
    Estimated activity duration in minutes.
  • Title: End Time
    Predicted or actual end time of activity in "YYYY-MM-DD HH:MM:SS" format, in the time zone of the resource the activity is assigned to.
  • Title: First Manual Operation
    Name of first manual operation on this activity
  • Title: First Manual Operation User
    User who performed the first manual operation on this activity
  • Title: Language
    customer's preferred language. When setting this field, the following language codes are accepted: Supported Language Codes.
  • Title: Latitude
    Minimum Value: -90
    Maximum Value: 90
    activity coordinates
  • Title: Longitude
    Minimum Value: -180
    Maximum Value: 180
    activity coordinates
  • Title: Master Activity Id
    This field is not set for regular activities. It is present for activities which are segments of a multiday activity - which have recordType=multiday_activity_segment. This is the activityId of the multiday activity.
  • Title: Multiday Activity Status
    Status of multiday activity
  • Title: Multiday Time To Complete
    Total duration of multiday activity
  • Title: Points
    Minimum Value: 0
    Maximum Value: 65535
    Activity cost in "points". This field is intended for use by Routing module
  • Title: Position In Route
    Position of activity in the route. Absent for not-ordered activities. 1-based number for ordered activities.
  • Title: Postal Code
    customer's postal code. Note: this field is used by geocoding and, therefore, must contain a valid address. Other values will not be resolved correctly by the geocoding server.
  • Title: Record Type
    Allowed Values: [ "regular", "reopened", "prework", "multiday_activity", "multiday_activity_segment" ]
    Type of activity record. Values are: "regular" - default value for most new activities."prework" - is created in Oracle Field Service Cloud if technician needs to perform pre-work before the actual activity."reopened" - is created when an activity in a final status is reopened for some reason."multiday_activity" - can be created using this API when "activityType" specified indicates that this is a multiday activity."multiday_activity_segment" - a number of these activities is automatically created for multiday activities, based on their duration and time slot settings.
  • Title: Reminder Time
    Reminder notification time. How many minutes before the activity start time the customer should be notified
  • Title: Resource Id
    Id of the resource this activity is assigned to.
  • Title: Resource Time Zone
    Time zone of the resource this activity is assigned to (e.g. "Eastern").

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

  • Title: Resource Time Zone Diff
    Difference in minutes between UTC and the the resource's local time. (e.g. -180 means resource time is 3 hours behind UTC).

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

  • Title: Resource Time Zone IANA name
    IANA name of the resource's time zone. (e.g. "America/New_York").

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

  • Title: Service Window End
    Service window end time in "HH:MM:SS" format.

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

  • Title: Service Window Start
    Service window start time in "HH:MM:SS" format.

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

  • Title: Sla Window End
    SLA end time in "YYYY-MM-DD HH:MM:SS" format.

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

  • Title: Sla Window Start
    SLA start time in "YYYY-MM-DD HH:MM:SS" format.

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

  • Title: Start Time
    This field represents the estimated time of arrival for activities in "pending" status, actual start time for activities in "started", "completed" status. In "YYYY-MM-DD HH:MM:SS" format, in the time zone of the resource the activity is assigned to.
  • Title: State Province
    customer's state / province. Note: this field is used by geocoding and, therefore, must contain a valid address. Other values will not be resolved correctly by the geocoding server.
  • Title: Status
    Allowed Values: [ "cancelled", "completed", "suspended", "started", "pending", "notdone" ]
    As the technician performs the activity, it changes its status. Based on this status different actions are available for an activity. Initial status is "pending" for newly created activities, after that they can be "cancelled" or "started". Activities with status "started" can be made "complete", "notdone", or "suspended".
  • Title: Street Address
    customer's address. Note: this field is used by geocoding and, therefore, must contain a valid address. Other values will not be resolved correctly by the geocoding server.
  • Title: Team Resource Id
    Id of the team resource if this activity is a team work
  • Title: Time Delivered End
    An arrival interval end time as communicated to the end customer
  • Title: Time Delivered Start
    An arrival interval start time as communicated to the end customer
  • Title: Time Of Assignment
    Time of assignment
  • Title: Time Of Booking
    Time of booking
  • Title: Time Slot
    Activity Time Slot. It defines the service window
  • Title: Time Zone
    Customer's time zone name. Example: "Eastern"

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

  • Title: Time Zone
    IANA name of the time zone. (https://www.iana.org/time-zones). Example: "America/New_York".

    Note this field is read-only, but when creating/updating an activity, the field "timeZone" accepts both IANA names and OFSC-specific names.

  • Title: Travel Time
    Estimated travel time to this activity. Estimate is based on previous activity in route
  • Title: Work Zone
    An activity work zone. It is a read-only field that is assigned to activity automatically based on the company setting "work zone key" and the activity properties. E.g. if "work zone key" is "first 4 symbols of city field", then activity with city="Belfast" will have assigned a work zone, which has "BELF" set up as one of its keys.

Default Response

Error response
Body ()
Root Schema : Error
Type: object
Show Source

Examples

The following example shows how to create a new activity by submitting a POST request on the REST resource using cURL.

curl -X 'POST' \
     -u 'user@instanceId:passwd' \
     -H 'Content-Type: application/json' \
     --data-binary '{
      "resourceId": "RXXXXX123",
      "date": "2017-08-17",
      "apptNumber": "ApptNumber",
      "activityType": "4",
      "duration": 60,
      "timeSlot": "all-day",
      "customerName": "John Doe",
      "streetAddress": "12345 Stuyvesant Ave",
      "city": "Brooklyn",
      "postalCode": "11221",
      "stateProvince": "NY",
      "accessSchedule": "{\"schedule\":[{\"daysOfWeek\":[\"Mon\",\"Tue\",\"Wed\",\"Thu\",\"Fri\",\"Sat\",\"Sun\"],\"hours\":[[\"07:00\",\"12:00\"]]}],\"exceptDates\":[\"2017-08-18\"]}",
      "setPositionInRoute": {
          "position": "first"
      }
}'  'https://api.etadirect.com/rest/ofscCore/v1/activities'

Example of Response Header

The following shows an example of the response header.

HTTP/1.1 201 Created
Server: nginx/1.2.7
Date: Fri, 18 Mar 2016 02:19:49 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": 4225449,
   "resourceId": "RXXXXX123",
   "accessSchedule": "{\"schedule\":[{\"daysOfWeek\":[\"Mon\",\"Tue\",\"Wed\",\"Thu\",\"Fri\",\"Sat\",\"Sun\"],\"hours\":[[\"07:00\",\"12:00\"]]}],\"exceptDates\":[\"2017-08-18\"]}",
   "resourceInternalId": 8101380,
   "date": "2017-08-17",
   "apptNumber": "ApptNumber",
   "recordType": "regular",
   "status": "pending",
   "activityType": "4",
   "duration": 39,
   "travelTime": 30,
   "timeSlot": "all-day",
   "customerName": "John Doe",
   "streetAddress": "12345 Stuyvesant Ave",
   "city": "Brooklyn",
   "postalCode": "11221",
   "stateProvince": "NY",
   "language": "en",
   "languageISO": "en-US",
   "timeZone": "(UTC-03:00) Buenos Aires - Argentine Time (ART)",
   "timeZoneIANA": "America/Argentina/Buenos_Aires",
   "deliveryWindowStart": "09:00:00",
   "deliveryWindowEnd": "10:00:00",
   "startTime": "2017-08-17 09:30:00",
   "endTime": "2017-08-17 10:09:00",
   "positionInRoute": 1,
   "timeOfBooking": "2017-08-17 08:20:28",
   "timeOfAssignment": "2017-08-17 08:20:28",
   "resourceTimeZone": "(UTC-03:00) Sao Paulo - Brasilia Time (BRT)",
   "resourceTimeZoneIANA": "America/Sao_Paulo",
   "resourceTimeZoneDiff": -180,
   "requiredInventories":
   {
       "links": [
           {
               "rel": "canonical",
               "href": "/rest/ofscCore/v1/activities/4225449/requiredInventories"
           }
       ]
   },
   "linkedActivities": {
       "links": [
           {
              "rel": "canonical",
              "href": "https://api.etadirect.com/rest/ofscCore/v1/activities/4225449/linkedActivities"
           }
       ]
   },
   "resourcePreferences": {
       "links": [
           {
              "rel": "canonical",
              "href": "https://api.etadirect.com/rest/ofscCore/v1/activities/4225449/resourcePreferences"
           }
       ]
   },
   "workSkills": {
       "links": [
           {
              "rel": "canonical",
              "href": "https://api.etadirect.com/rest/ofscCore/v1/activities/4225449/workSkills"
           }
       ]
   },
   "links":
   [
      {
         "rel": "canonical",
         "href": "https://api.etadirect.com/rest/ofscCore/v1/activities/4225449"
      },
      {
         "rel": "describedby",
         "href": "https://api.etadirect.com/rest/ofscCore/v1/metadata-catalog/activities"
      },
      {
         "rel": "route",
         "href": "https://api.etadirect.com/rest/ofscCore/v1/resources/RXXXXX123/routes/2017-08-17"
      }
   ]
}