Supported Activity Actions
You can create scheduled and non-scheduled activities through custom plug-ins. For example, a custom plug-in to check the expected delivery of a part can create a follow-up activity for a repair job using the part. You can achieve this using the activity action ‘create’, which is available for the ‘close’ method.
create Method Parameters
Parameter Name | Mandatory | Type | Description |
---|---|---|---|
temporaryAid | No | String |
Temporary ID of a created activity. If the param is not set, the temporary aid is generated by Oracle Field Service. The value must be unique, that is, must not duplicate a temporary aid of any existing activity. The value must be a string that matches the regular expression: /^\d+\-\d{4}p?$/ . The length of the string must be less than or equal to 25. |
activityType | Yes | String | Label of one of the Activity Types, configured for Oracle Field Service (for example, "LU"). Activity types with enabled features "Allow mass activities", "Allow repeating activities" or "Enable segmenting and extended duration" are not allowed. |
date | No | String | Date in YYYY-MM-DD format defined by ISO 8601 (for example, "2019-11-28") If the date is not set, or is empty (null or empty string), the activity is created for the date of the currently selected route. Is forbidden for scheduled equal to false. |
scheduled | No | Boolen | If scheduled is true, the activity is scheduled for date defined by value of date parameter. If scheduled is false, the activity is created as not scheduled. Non-scheduled activities can be created only for Activity types that have the "Allow non-scheduled" feature enabled. Default value: true |
positionInRoute | No | Object | The value of this parameter determines the position of the
activity in the route. It's the object with two fields:
Default value: { position: "last" } |
duration | No | Number | Duration of activity in minutes (integer number). Minimal value: 0, maximal value: 65535. Duration can be set only for Activity types that have the "Calculate activity duration using statistics" feature disabled. |
timeSlot | No | String | The label of one of Time Slots configured in Oracle Field Service.
The time slot defines the service window for the activity. The timeSlot
parameter can be set only for Activity types that have the "Support
of time slots" feature enabled. If set, the value of timeSlot must contain the label of one of the timeslots that are selected in the "Available time slots" section of Activity Type configuration. |
serviceWindowStart | No | String | The time when the service window starts for the activity in hh:mm format defined by ISO 8601 (for example, "14:07" ) The serviceWindowStart parameter can be set only for Activity types that have the "Support of time slots" feature disabled. |
serviceWindowEnd | No | String | The time when the service window ends for the activity in hh:mm format defined by ISO 8601 (e.g. "09:56") The serviceWindowStart parameter can be set only for Activity types that have the "Support of time slots" feature disabled. |
slaWindowStart | No | String | The time when the service level agreement (SLA) window starts. The date and time must be in the format "YYYY-MM-DD hh:mm" or "YYYY-MM-DD hh:mm:ss" (for example, "2019-12-16 16:42"). |
slaWindowEnd | No | String | The time when the service level agreement (SLA) window ends.
The date and time must be in the format "YYYY-MM-DD hh:mm" or "YYYY-MM-DD
hh:mm:ss" (for example, "2019-12-20 16:42"). If slaWindowStart is specified then slaWindowEnd must be equal or greater than slaWindowStart (slaWindowEnd ≥ slaWindowStart). |
properties | No | Object | Is a key-value object, where keys are the labels of Oracle Field Service activity properties to be written. Properties are validated and processed according to the way the plug-in is configured. |
Error Codes for Activity Actions
Code | Caused by Action | Cause |
---|---|---|
CODE_ACTION_PARAM_NOT_UNIQUE | create |
Value of "temporary_aid" param of "create" activity action duplicates the value of "temporary_aid" field of another activity in the route. |
TYPE_ACTION_ERROR | ||
CODE_ACTION_NUMBER_LIMIT_EXCEEDED | create | Number of items in the "actions" field of close or update message is greater than 10,000. |
CODE_ACTION_ON_PAST_DATE_NOT_ALLOWED | create | Any of these:
|
CODE_ACTION_UNKNOWN | N/A | "action" parameter is not equal to one of the "create" |
CODE_ACTION_ENTITY_UNKNOWN | N/A | "entity" parameter is not equal to "activity" or "inventory" |
TYPE_ACTION_PARAM | ||
CODE_ACTION_ACTIVITY_TYPE_INVALID | create | Any of these:
|
CODE_ACTION_DATE_FORBIDDEN | create | The "scheduled" parameter is false and "date" parameter is set. |
CODE_ACTION_NOT_SCHEDULED_FORBIDDEN | create | The "scheduled" parameter is false and the "activityType" parameter contains the label of the Activity type for which the feature "Allow non-scheduled" is disabled. |
CODE_ACTION_TIME_SLOT_FORBIDDEN | create | The "timeSlot" parameter is set and the "activityType" parameter contains the label of Activity type for which the feature "Support of time slots" is disabled. |
CODE_ACTION_TIME_SLOT_NOT_AVAILABLE | create | The "timeSlot" parameter contains the label of the time slot, which is not selected in the "Available time slots" section of Activity Type configuration. |
CODE_ACTION_SW_FORBIDDEN | create | "serviceWindowStart" or "serviceWindowEnd" parameter is set and "activityType" parameter contains the label of the Activity type for which the feature "Support of time slots" is enabled. |
CODE_ACTION_MANDATORY_PARAM_EMPTY | create | The "activityType" parameter is not set. |
CODE_ACTION_PARAM_VALUE_INVALID | create | Any of these:
|
TYPE_ACTION_PROPERTY | ||
CODE_ACTION_PROPERTY_VALUE_INVALID | create | Any of these:
|
CODE_ACTION_PROPERTY_VALUE_TOO_LARGE | create | Any of these:
|
TYPE_INTERNAL | ||
CODE_UNKNOWN | create | Oracle Field Service is unable to process the message due to an unexpected change in the system's state. |
Example of close Method to Create an Activity
{
"apiVersion": 1,
"method": "close",
"actions": [
{
"entity": "activity",
"action": "create",
"activityType": "SDI",
"scheduled": true,
"date": "2019-12-12",
"timeSlot": "",
"positionInRoute": {
"position": "afterActivity",
"activityId": "4225450"
},
"serviceWindowStart": "10:00",
"serviceWindowEnd": "11:30",
"properties": {
"WO_COMMENTS": "Follow-up activity"
}
}
]
}
Temporary ID
Each time a new instance of an Oracle Field Service entity (Activity or Inventory) is created on a user's device, a temporary ID is generated. This happens regardless of whether the instance is created through the plug-in API or through a standard page such as Add activity or one of the Inventory pages. The temporary ID used as a value of the Activity ID (aid) and Inventory ID (invid) fields until data is synchronized with the server, so the user and the plug-ins may operate the newly created entities even offline. After synchronization, the temporary ID is replaced with an actual aid or invid generated by the server.
- The value of the client-generated temporary id is stored in the "temporary_aid" field of the activity, which persists even after data is synced with server and a permanent aid (generated by a server) is obtained.
- Temporary aid may be used as a valid value of the "inv_aid" param for all inventory actions, "inv_aid" field for "inventoryList" and "inventory" collection updates, and as an activity key for the "activityList" collection updates even after synchronization with server.
- The plug-in may generate a temporary id for activities on its own and send it in the "temporaryAid" param of the "create" activity action. The plug-in may store this value and use it to reference a created activity in later acctions not even knowing the actual aid.
- The plug-in can use the value of the generated temporaryAid as a value of the inv_aid param for inventory actions even in the same close or update message as the create activity action itself.
The temporary_aid field is not available for segmentable, mass, and repeating activities as the number and actual IDs of segments or instances may be changed at any time.
Example of actions that make use of temporaryAid:
{
"apiVersion": 1,
"method": "update",
"activityList": {
"16297679485790-0793": {
"astatus": "cancelled"
}
}
"actions": [
{
"entity": "activity",
"action": "create",
"temporaryAid": "16297673252100-2175p",
"activityType": "4",
"scheduled": true,
"date": "2021-08-23"
},
{
"entity": "inventory",
"action": "create",
"inv_aid": "16297673252100-2175p",
"invtype": "NT",
"invpool": "customer",
"properties": {
"invsn": "KCD1403WH"
}
}
]
}