1. Mobile Plug-in Framework
  2. Supported Activity Actions

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.

Note: The plug-in can create activities only on the route of the currently selected resource.

create Method Parameters

This table provides the parameters of the create method.
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:

  • position (string) - one of these values: "first", "last", "notOrdered", "afterActivity"

  • activityId (string) - the unique identifier of the activity in Oracle Field Service. If the value of the field 'position' is 'afterActivity', then created activity is scheduled right after activity with given activityId

The "afterActivity" value of position field is not allowed, if the date parameter is not empty and is not equal to the date of the currently selected route. Not-ordered activities can be created only for Activity types that have the "Support of not-ordered activities" feature enabled.

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

This table describes the error codes that are displayed for activity actions, and the reason for which they are displayed.
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:

  • "date" parameter of "create" action is set and the currently selected queue is in the past (and overnight has ended).

  • "date" parameter of the "create" action equals the date of the currently selected queue and the selected queue is in the past (and overnight has ended).

  • "date" parameter of the "create" action contains the date, which is earlier than the local date (that is, the date in the Resource's time zone) of currently the selected Resource.
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:

  • "activityType" parameter value is not equal to the label of one of the Activity Types, configured for Oracle Field Service

  • "activityType" parameter contains the label of Activity type, for which any of these features is enabled:

    • Allow mass activities

    • Allow repeating activities

    • Enable segmenting and extended duration
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:

  • "date" parameter is set and its value is not a valid date string in YYYY-MM-DD format defined by ISO 8601

  • "scheduled" parameter is set and its value is not a boolean

  • "duration" parameter is not an integer or out of range

  • "timeSlot" parameter is set and its value is not equal to the label of one of the Time Slots, configured for OFS

  • "timeSlot" parameter is set and its value is not a string

  • "serviceWindowStart" parameter is set and its value is not a valid time sting in hh:mm format defined by ISO 8601

  • "serviceWindowEnd" parameter is set and its value is not a valid time string in hh:mm format defined by ISO 8601

  • "positionInRoute" is set and is not an object

  • "position" field's value of "positionInRoute" parameter doesn't equal one of these: "first", "last", "notOrdered", "afterActivity"

  • "position" field of "positionInRoute" is "afterActivity" and "scheduled" parameter is false

  • "position" field of "positionInRoute" is "afterActivity" and "date" parameter is set and it is not equal to the date of the currently selected queue

  • The "position" field of "positionInRoute" is "afterActivity" and the "activityId" field of the "positionInRoute" parameter is not set, or it is not equal to the Activity ID of one of the activities in the currently-selected queue.
TYPE_ACTION_PROPERTY
CODE_ACTION_PROPERTY_VALUE_INVALID create Any of these:

  • Property type is 'file', its GUI type is 'signature' and its value is not a valid Data URI or it has the invalid MIME-type.

  • Property type is 'enumeration', and its value is not a valid enumeration item's index.
CODE_ACTION_PROPERTY_VALUE_TOO_LARGE create Any of these:

  • Property type is 'field' and length of its value exceeds 119 UTF-16 code points.

  • Property type is 'file', its GUI type is 'signature' and length of its value exceeds 102400 UTF-16 code points.

  • Property is neither field nor signature and length of its value exceeds 32767 UTF-16 code points.

See Property value's length limits for details.
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.

To allow the plug-in perform any operation on activities created on the client-side (using the "create" action of the plug-in API or the standard Add activity page), both in offline in online, the plug-in API provides the following:
  • 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"
            }
        }
    ]
}