Create new activity
/rest/ofscCore/v1/activities
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
-
object New activity properties
Title:
New activity properties
Activity properties
object
New activity properties
-
accessSchedule:
string
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" }
}
}
} -
activityType:
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 -
apptNumber:
string
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. -
city:
string
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. -
country_code:
string
Title:
Country code
Country code -
customerCell:
string
Title:
Customer Cell
customer's cell phone number -
customerEmail:
string
Title:
Customer Email
customer's email address -
customerName:
string
Title:
Customer Name
customer's name. -
customerNumber:
string
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. -
customerPhone:
string
Title:
Customer Phone
customer's regular (land) phone number -
date:
string
Title:
Date
Date this activity is scheduled. This field can be absent, meaning the activity is not scheduled for any particular date -
deliveryWindowEnd:
string
Title:
Delivery Window End
activity delivery window end time in HH:MM:SS format -
deliveryWindowStart:
string
Title:
Delivery Window Start
activity delivery window start time in HH:MM:SS format -
duration:
integer
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. -
language:
string
Title:
Language
Customer's preferred languageThis 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.
-
latitude:
number
Title:
Latitude
Minimum Value:-90
Maximum Value:90
activity coordinates -
longitude:
number
Title:
Longitude
Minimum Value:-180
Maximum Value:180
activity coordinates -
points:
integer
Title:
Points
Minimum Value:0
Maximum Value:65535
Activity cost in "points". This field is intended for use by Routing module -
postalCode:
string
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. -
reminderTime:
integer
Title:
Reminder Time
Reminder notification time. How many minutes before the activity start time the customer should be notified -
resourceId:
string
Title:
Resource Id
Id of the resource this activity is assigned to. -
serviceWindowEnd:
string
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.
-
serviceWindowStart:
string
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.
-
setPositionInRoute:
object Set Position in Route
Title:
Set Position in Route
If this element is present then activity will be put to specified position in route -
setTravelTime:
object 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. -
slaWindowEnd:
string
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.
-
slaWindowStart:
string
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.
-
stateProvince:
string
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. -
streetAddress:
string
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. -
teamResourceId:
string
Title:
Team Resource Id
Id of the team resource if this activity is a team work -
timeDeliveredEnd:
string
Title:
Time Delivered End
An arrival interval end time as communicated to the end customer -
timeDeliveredStart:
string
Title:
Time Delivered Start
An arrival interval start time as communicated to the end customer -
timeOfAssignment:
string
Title:
Time Of Assignment
Time of assignment -
timeOfBooking:
string
Title:
Time Of Booking
Time of booking -
timeSlot:
string
Title:
Time Slot
Activity Time Slot. It defines the service window -
timeZone:
string
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.
object
Set Position in Route
-
activityId:
integer
Title:
activityId
If "position" is "afterActivity" then this is the activityId after which the other activity will be put -
position:
string
Title:
position
Allowed Values:[ "first", "last", "notOrdered", "byServiceWindow", "afterActivity" ]
position in route
object
Set travel time
-
position:
string
Title:
Position
Allowed Values:[ "first", "afterActivity" ]
Expected position of the activity in a routeIn 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:
object 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.
-
previousActivityId:
integer
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.
-
source:
string
Title:
Source
Allowed Values:[ "manual", "external" ]
Origin of the provided travel time dataThe '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.
-
travelTime:
integer
Title:
Travel time
Minimum Value:0
Maximum Value:65535
Travel time to the specified activity
object
previousActivity
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.
Response
- application/json
201 Response
object
Activity properties
-
accessSchedule:
string
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" }
}
}
} -
activityId:
integer
Title:
Activity Id
Unique identifier of activity in Oracle Field Service Cloud -
activityType:
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 -
apptNumber:
string
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. -
city:
string
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. -
country_code:
string
Title:
Country code
Country code -
customerCell:
string
Title:
Customer Cell
customer's cell phone number -
customerEmail:
string
Title:
Customer Email
customer's email address -
customerName:
string
Title:
Customer Name
customer's name. -
customerNumber:
string
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. -
customerPhone:
string
Title:
Customer Phone
customer's regular (land) phone number -
date:
string
Title:
Date
Date this activity is scheduled. This field can be absent, meaning the activity is not scheduled for any particular date -
deliveryWindowEnd:
string
Title:
Delivery Window End
activity delivery window end time in HH:MM:SS format -
deliveryWindowStart:
string
Title:
Delivery Window Start
activity delivery window start time in HH:MM:SS format -
duration:
integer
Title:
Duration
Minimum Value:0
Maximum Value:65535
Estimated activity duration in minutes. -
endTime:
string
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. -
firstManualOperation:
string
Title:
First Manual Operation
Name of first manual operation on this activity -
firstManualOperationUser:
string
Title:
First Manual Operation User
User who performed the first manual operation on this activity -
language:
string
Title:
Language
customer's preferred language. When setting this field, the following language codes are accepted: Supported Language Codes. -
latitude:
number
Title:
Latitude
Minimum Value:-90
Maximum Value:90
activity coordinates -
longitude:
number
Title:
Longitude
Minimum Value:-180
Maximum Value:180
activity coordinates -
masterActivityId:
integer
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. -
multidayActivityStatus:
string
Title:
Multiday Activity Status
Status of multiday activity -
multidayTimeToComplete:
string
Title:
Multiday Time To Complete
Total duration of multiday activity -
points:
integer
Title:
Points
Minimum Value:0
Maximum Value:65535
Activity cost in "points". This field is intended for use by Routing module -
positionInRoute:
integer
Title:
Position In Route
Position of activity in the route. Absent for not-ordered activities. 1-based number for ordered activities. -
postalCode:
string
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. -
recordType:
string
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. -
reminderTime:
integer
Title:
Reminder Time
Reminder notification time. How many minutes before the activity start time the customer should be notified -
resourceId:
string
Title:
Resource Id
Id of the resource this activity is assigned to. -
resourceTimeZone:
string
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.
-
resourceTimeZoneDiff:
integer
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
-
resourceTimeZoneIANA:
string
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
-
serviceWindowEnd:
string
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.
-
serviceWindowStart:
string
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.
-
slaWindowEnd:
string
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.
-
slaWindowStart:
string
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.
-
startTime:
string
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. -
stateProvince:
string
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. -
status:
string
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". -
streetAddress:
string
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. -
teamResourceId:
string
Title:
Team Resource Id
Id of the team resource if this activity is a team work -
timeDeliveredEnd:
string
Title:
Time Delivered End
An arrival interval end time as communicated to the end customer -
timeDeliveredStart:
string
Title:
Time Delivered Start
An arrival interval start time as communicated to the end customer -
timeOfAssignment:
string
Title:
Time Of Assignment
Time of assignment -
timeOfBooking:
string
Title:
Time Of Booking
Time of booking -
timeSlot:
string
Title:
Time Slot
Activity Time Slot. It defines the service window -
timeZone:
string
Title:
Time Zone
Customer's time zone name. Example: "Eastern"For a list of supported time zones, see Supported Time Zones.
-
timeZoneIANA:
string
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.
-
travelTime:
integer
Title:
Travel Time
Estimated travel time to this activity. Estimate is based on previous activity in route -
workZone:
string
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
object
-
detail:
string
Detailed information about the error
-
status:
string
HTTP status code
-
title:
string
Summary error message
-
type:
string
A URL of a page containing details of this error
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" } ] }