1. Mobile Plug-in Framework
  2. open Method

open Method

When a user opens a plug-in through a button, a message with the open method is sent to the plug-in after Oracle Field Service receives the ready message. The response of the 'open' method contains the 'user' item, includes the 'main_resource_id' field that represents the resource which is referenced to the current user. Similarly, the response of the 'open' method includes the 'team' item, which contains information about teamwork. The response of the 'open' method also contains the 'queue' key with current queue state (activated, not activated, or deactivated). The 'resource' key contains the time-related fields such as the current resource's time, resource's time zone difference, and the difference between a device's clock and UTC.

The open message contains entity collections, for example, data of available Oracle Field Service entities such as activities and inventories. See Available entities and data collections for details. The 'dataItems' option of the 'ready' method controls the availability of the ‘team’ item. The 'team' item is not sent if the plug-in is opened from the Main menu. The response of the 'open' method is extended with the activity and inventory lists when they are available.

Example of open message
{
    "apiVersion": 1,
    "method": "open",
    "entity": "activity",
    "user": {
        "uid": 38,
        "ulogin": "rayner",
        "uname": "RAYNER, Faye",
        "format": {
            date: "m/d/y",
            long_date: "l, F jS, Y",
            time: "h:i A",
            datetime: "m/d/y h:i A"
        },
        "su_zid": 4,
        "week_start": 0,
        "ulanguage": 1,
        "languageCode": "en",
        "design_theme": 11,
        "allow_vibration": 1,
        "allow_desktop_notifications": 0,
        "sound_theme": 11,
        "providers": [
            "5000038",
            "5000039"
        ],
        "main_resource_id": 5000038
    },
    "team": {
        "assistingTo": {
            "3000001": [
                "3000008",
                "3000037"
            ],
            "3000015": []
        },
        "assistingMe": [
            "3000003",
            "3000008"
        ],
        "teamMembers": {
            "3000001": {
                "uid": 1000001,
                "external_id": "resource_1",
                "pname": "Resource 1",
                "pactive": 1
            },
            "3000003": {
                "uid": 1000003,
                "external_id": "resource_13",
                "pname": "Resource 3",
                "pactive": 1
            },
            "3000008": {
                "uid": 1000008,
                "external_id": "resource_8",
                "pname": "Resource 8",
                "pactive": 1
            },
            "3000015": {
                "uid": 1000015,
                "external_id": "resource_15",
                "pname": "Resource 15",
                "pactive": 1
            },
            "3000037": {
                "uid": 1000037,
                "external_id": "resource_37",
                "pname": "Resource 37",
                "pactive": 1
            }
        }
    },
    "resource": {
        "pid": 5000038,
        "pname": "RAYNER, Faye",
        "external_id": "55038",
        "gender": "1"
    },
    "activityiList": {
        "3956534": {
            "WO_COMMENTS": "AUTOMATIC TRANSFER WORK ORDER\n\n",
            "astatus": "started",
            "aid": 3956534
        }
    },
    "activity": {
        "WO_COMMENTS": "AUTOMATIC TRANSFER WORK ORDER\n\n",
        "astatus": "started",
        "aid": 3956534
    },
    "inventoryList": {
        "20997919": {
            "invid": 20997919,
            "inv_aid": 3956534,
            "inv_pid": 5000038,
            "invpool": "install",
            "invsn": "SABDFWKNZ"
        },
        "20998078": {
            "invid": 20998078,
            "inv_aid": 3956532,
            "invpool": "customer",
            "invsn": "5CTBME4AW090379"
        },
        "20998080": {
            "invid": 20998080,
            "inv_aid": 3956533,
            "invpool": "customer",
            "invsn": "SABGZTWGM"
        }
    }
}
Example of the open message for a plug-in opened from the Main menu (only 'user' collection is available)
{
    "apiVersion": 1,
    "method": "open",
    "entity": "user",
    "user": {
        "uid": 2315,
        "ulogin": "admin",
        "uname": "Admin",
        "format": {
            "date": "m/d/y",
            "long_date": "l, F jS, Y",
            "time": "h:i A",
            "datetime": "m/d/y h:i A"
        },
        "week_start": 0,
        "ulanguage": 1,
        "language": "en",
        "design_theme": 1,
        "allow_vibration": 0,
        "allow_desktop_notifications": 0,
        "sound_theme": 0,
        "providers": [
            2
        ]
    }
}
Example of the open message for a plug-in opened from the Parts Catalog
{    
    "apiVersion": 1,    
    "method": "open",    
    "entity": "partsCatalogItem",
    "team": {
        "assistingTo": {},
        "assistingMe": [],
        "teamMembers": {}
    },
    "user": {
        "uid": 2315,
        "ulogin": "admin",
        "uname": "Admin",
        "format": {
            "date": "m/d/y",
            "long_date": "l, F jS, Y",
            "time": "h:i A",
            "datetime": "m/d/y h:i A"
        },
        "week_start": 0,
        "ulanguage": 1,
        "languageCode": "en",
        "design_theme": 1,
        "allow_vibration": 0,
        "allow_desktop_notifications": 0,
        "sound_theme": 0,
        "providers": [
            2
        ]
    },
    "partsCatalogItem": {        
        "catalogId": 2,
        "label": "a5123-df"
    },
    "resource": {
        "pid": 5000038,
        "pname": "RAYNER, Faye",
        "external_id": "55038",
        "gender": "1"
    },
    "activityiList": {
        "3956534": {
            "WO_COMMENTS": "AUTOMATIC TRANSFER WORK ORDER\n\n",
            "astatus": "started",
            "aid": 3956534
        }
    },
    "inventoryList": {
        "20997919": {
            "invid": 20997919,
            "inv_aid": 3956534,
            "inv_pid": 5000038,
            "invpool": "install",
            "invsn": "SABDFWKNZ"
        }
    }
}
Structure of the 'team' collection in the ‘open’ method when teamwork is not set:
"team": {
    "assistingTo": {},
    "assistingMe": [],
    "teamMembers": {}
}
Structure of the 'team' collection in the ‘open’ method when teamwork is set:
"team": {
    "assistingTo": { - object with list of resources who I am assisting to
        "3000001": [ - array with list of additional resources who is assisting to user who I am assisting to (current user 3000035 is absent in this list!)
            "3000008", - resource ID who is also assisting to resource 3000001
            "3000037"
        ],
        "3000015": []
    }
    "assistingMe": [ - array with list of resources who is assisting me
        "3000003", - resource ID who is assisting to me
        "3000008"
    ]
    "teamMembers": { - object with information of all team members
        "3000001": {
            "uid": 1000001, - the resource is main resource for this user ID
            "external_id": "resource_1", - resource external ID
            "pname": "Resource 1", - resource name
        },
        "3000003": {
            "uid": 1000003,
            "external_id": "resource_13",
            "pname": "Resource 3"
        },
        "3000008": {
            "uid": 1000008,
            "external_id": "resource_8",
            "pname": "Resource 8"
        },
        "3000015": {
            "uid": 1000015,
            "external_id": "resource_15",
            "pname": "Resource 15"
        },
        "3000037": {
            "uid": 1000037,
            "external_id": "resource_37",
            "pname": "Resource 37"
        }
    }
}

Example of "open" message for Plugin opened via deep link

{
    "apiVersion": 1,
    "method": "open",
    "entity": "activityList",
    "resource": {},
    "team": {
        "assistingTo": {},
        "assistingMe": [],
        "teamMembers": {}
    },
    "user": {
        "uid": 2315,
        "ulogin": "admin",
        "uname": "Admin",
        "format": {
            "date": "m/d/y",
            "long_date": "l, F jS, Y",
            "time": "h:i A",
            "datetime": "m/d/y h:i A"
        },
        "week_start": 0,
        "ulanguage": 1,
        "languageCode": "en",
        "design_theme": 1,
        "allow_vibration": 0,
        "allow_desktop_notifications": 0,
        "sound_theme": 0,
        "providers": [
            2
        ]
    },
    "activityList": {
        "4225438": {
            "aid": "4225438"
        },
        "4225439": {
            "aid": "4225439"
        }
    },
    "inventoryList": {
        "21064417": {
            "invid": "21064417"
        },
        "21064418": {
            "invid": "21064418"
        }
    },
    "openParams": {},
    "externalData": {
        "zipcodes": ["35801", "06101", "62701"],
        "status": "completed"
    }
}

Available Entities and Data Collections

The field 'entity' and entity data collections are available only for 'open' and 'close' methods. The value of the special 'entity' field depends on the Oracle Field Service Core Application page from which the user opens the plug-in. Availability of entity data collections that are sent within the message data, depends on the value of 'entity'. this table gives the available entities and data collections for the open method:
Page Entity Field Value Available Collections
Main menu

Team Map

 user user
Activity List

Route Map

 activitiyList

user

team

queue

resource

activitiyList

inventoryList
Activity List -> Inventory List inventoryList
Activity List -> Activity Details activity

user

team

queue

resource

activityList

activity

inventoryList
Activity List -> Activity Details -> Inventory List activityInventoryList
Activity List -> Inventory List -> Inventory Details inventory

user

team

queue

resource

activitiyList

inventoryList

inventory
Activity List -> Activity Details -> Inventory List -> Inventory Details activityInventory

user

team

queue

resource

activityList

activity

inventoryList

inventory
Inventory Search -> Parts Catalog Item Details partsCatalogItem

user

team

queue

resource

activitiyList

inventoryList

partsCatalogItem
Entity Data Collections
  • team: Information about assistants and resources who are assisting to the current resource

  • resource: Element in the resource tree representing a defined company asset

  • activity: Entity of Oracle Field Service that represents any time-consuming activity of the resource

  • activityList: Activity list

  • inventory: Equipment that can be installed or deinstalled during an activity

  • inventoryList: Inventory list

  • user: User who has currently logged in to Oracle Field Service Core Application and opens the plug-in

  • partsCatalogItem: Information that identifies the parts catalog item, so it can be retrieved using the getParts procedure

Note: The 'team', 'resource', 'user', and 'partsCatalogItem' collections can't be updated through the plug-in API and are ignored if they're sent with the 'close' message.

Availability of activity, inventory, and resource properties depends on the configuration of the plug-in. See Available Properties for details.

Available Fields for 'user' Entity Collection

The available properties for this entity are predefined and do not depend on the configuration of the plug-in. this table provides the available fields for the ‘user’ entity collection:
Field Type Example Value Description
uid Number 2315 Internal id of user
ulogin String admin Login
uname String Admin Name
format Object<String, String> 
{
     "date": "m/d/y",
     "long_date": "l, F jS, Y",
     "time": "h:i A",
     "datetime": "m/d/y h:i A"
}
 Collection of date format strings in the PHP's style
su_zid Number 2 Time Zone id
week_start Number 0 Week start day (0-6)

0 - Sunday, 1 - Monday
ulanguage Number 1 Language id (1 - English)
languageCode String en Two-letter code for the language
design_theme Number 1 Design theme ID
allow_vibration Number 0 1 - Vibration on mobile devices is allowed, 0 - disallowed
allow_desktop_notifications Number 0 1 - Browser desktop notifications are allowed, 0 - disallowed
sound_theme Number 0 Sound notification settings

0 - Off, 1 - Quiet, 2 - Loud, 3 - Persistent
providers Array<Number> [ 38, 3000001 ] List of resources, that are visible to user, excluding their descendants
main_resource_id (optional) Number 1111 Resource ID, which is set as the main resource
Available Fields for 'activity' Entity Collection
This table provides the available fields for the ‘activity’ entity collection:
Field Description
cname Name
caddress Address
ccity City
czip ZIP/Postal Code
cstate State
customer_number Account Number
c_zid Time Zone
cphone Phone
cemail Email
ccell Cellular Phone
atype Activity Type
position_in_route Position in Route
aworktype Activity type
time_slot Time Slot
service_window Service Window
appt_number Work Order
clanguage Message Language
cmessagetime Reminder
activity_workskills Work Skill
length Duration
ETA Start
astatus Activity status
aid Activity ID
end_time End
delivery_window Delivery Window
acoord_status Coordinate Status
acoord_x Coordinate X
acoord_y Coordinate Y
travel Traveling Time
sla_window_start SLA Start
sla_window_end SLA End
atime_of_booking Activity Time of Booking
atime_of_assignment Activity Time of Assignment
activity_flow Activity workflow
Non-Available Fields for 'activity' Entity Collection
This table provides the fields that are not available for the ‘activity’ entity collection:
Field Description
aworkzone Work Zone
time_delivered Time Notified
eta_end_time Start - End
date Date
pid Resource ID
apoints Points
atravelarea Travel Area
activity_capacity_categories Capacity Categories
activity_alerts Alerts
activity_compliance Compliance Alerts
auto_routed_to_provider_id Auto-Routed to Resource
auto_routed_to_date Auto-Routed to Date
first_manual_operation First Manual Operation
first_manual_operation_user_id First Manual Operation Performed by User
first_manual_operation_interface First Manual Operation Interface
auto_routed_to_provider_name Auto-Routed to Resource (Name)
first_manual_operation_user_name First Manual Operation Performed by User (Name)
first_manual_operation_user_login First Manual Operation Performed by User (Login)
access_hours Access Hours
access_schedule Access Schedule

'activity_flow'

The "activity_flow" field can be set from the plugin, or it will be calculated dynamically based on the workflow conditions created. The "activity_flow" field can be set for only those activities in status 'Pending' or 'En route'. Also, the "activity_flow" field can be set when the activity status is changed from 'Pending' or 'En route' to 'Started'. The dynamic calculation works when the activity status is changed from 'Pending' or 'En route' to 'Started' and "activity_flow" field was not ser previously; the application associates the workflow with the activity permanently, saves the workflow ID into the "activity_flow" field, and stops recalculation. It is prohibited to change the "activity_flow" field after an activity is started; a corresponding error message will be displayed.

'masterActivityId'

Each segment of a segmentable activity has a field called "masterActivityId". It's and id of the main activity which the segment belongs to. This field may be usable in a scenario when a plugin needs to deinstall inventory from a segmentable activity because customer pool inventory is assigned to the main segmentable activity (via "inv_aid" field) which is absent in the activity list. Using the "masterActivityId" activity field, the plugin can filter inventories from the "inventoryList" which belong to the main segmentable activity.

Example of an "open" message which contains segments of a segmentable activity and customer pool inventory
{
    "apiVersion": 1,
    "method": "open",
    "entity": "activityList",
    "user": {
        "allow_desktop_notifications": 1,
        "allow_vibration": 1,
        "design_theme": 11,
        "format": {
            "date": "m/d/y",
            "long_date": "l, F jS, Y",
            "time": "h:i A",
            "datetime": "m/d/y h:i A"
        },
        "providers": [
            2
        ],
        "sound_theme": 2,
        "su_zid": 15,
        "uid": 2315,
        "ulanguage": 1,
        "languageCode": "en",
        "ulogin": "admin",
        "uname": "Admin",
        "week_start": 0
    },
    "resource": {
        "pid": 3000037,
        "currentTime": "2021-08-30 05:21:23",
        "deviceUTCDiffSeconds": 0,
        "timeZoneDiffSeconds": -14400
    },
    "team": {
        "teamMembers": {},
        "assistingTo": {},
        "assistingMe": []
    },
    "queue": {
        "date": "2021-08-30",
        "status": "notActivated",
        "isActual": true
    },
    "activityList": {
        "4227119": {
            "acoord_status": null,
            "acoord_x": null,
            "acoord_y": null,
            "aworktype": "LU",
            "appt_number": null,
            "astatus": "pending",
            "aid": "4227119"
        },
        "4227120": {
            "acoord_status": null,
            "acoord_x": null,
            "acoord_y": null,
            "aworktype": "4",
            "appt_number": null,
            "astatus": "pending",
            "aid": "4227120"
        },
        "4227122": {
            "acoord_status": null,
            "acoord_x": null,
            "acoord_y": null,
            "aworktype": "Multiday",
            "appt_number": null,
            "astatus": "pending",
            "aid": "4227122",
            "masterActivityId": 4227121
        },
        "4227123": {
            "acoord_status": null,
            "acoord_x": null,
            "acoord_y": null,
            "aworktype": "Multiday",
            "appt_number": null,
            "astatus": "pending",
            "aid": "4227123",
            "masterActivityId": 4227121
        },
        "4227133": {
            "acoord_status": null,
            "acoord_x": null,
            "acoord_y": null,
            "aworktype": "Multiday",
            "appt_number": null,
            "astatus": "pending",
            "aid": "4227133",
            "masterActivityId": 4227132
        }
    },
    "inventoryList": {
        "21258560": {
            "invpool": "customer",
            "invid": "21258560",
            "inv_aid": 4227121,
            "inv_pid": null,
            "invsn": null,
            "invtype": "EC",
            "quantity": 42
        },
        "21258561": {
            "invpool": "customer",
            "invid": "21258561",
            "inv_aid": 4227132,
            "inv_pid": null,
            "invsn": null,
            "invtype": "HD12",
            "quantity": 100
        }
    },
    "buttonId": "20360",
    "openParams": {}
}

Available Fields for 'inventory' Entity Collection

This table provides the available fields for the ‘inventory’ entity collection:
Field Description
invsn Serial Number
invpool Inventory pool
invtype Inventory Type
invid Inventory Id
inv_aid Activity Id
inv_pid Resource Id
inv_change_invid Changed Inventory ID
quantity Quantity
Available Fields for ‘resource’ Entity Collection
This table provides the available fields for the ‘resource’ entity collection:
Field Description
email Email address
external_id External ID
pdate_fid Date format
pactive Status
pid ID
planguage Message Language
pname Name
pphone Phone
ptime_fid Time format
ptype Resource type
time_zone Time zone
currentTime Current time in "YYYY-MM-DD hh:mm:ss" format in the resource's time zone at the time of generating the "open" message.

deviceUTCDiffSeconds

Difference between browser's time and UTC (server time) in seconds.

A plug-in can calculate the actual UTC time using this formula: UTC = Math.round(new Date().getTime() / 1000) - deviceUTCDiffSeconds.
timeZoneDiffSeconds Provider's timezone diff in seconds at the time of generating the "open" message.
Unavailable Fields for 'resource' Entity Collection
This table provides the fields that are not available for the ‘resource’ entity collection:
Field Description
alerts Alerts
calendar Calendar
oncall_calendar On-call Calendar
organization_id Organization
p_rprid Routing profile
pcapacity_bucket Use as Capacity Area
pending Pending
pinitial_ratio Initial Ratio for Activity Duration
queue_status Queue status
reactivated Reactivated
resource_capacity_categories Capacity Categories
resource_effective_workskills Effective Work Skills
resource_time_slots Time slots
resource_workskills Work Skills
resource_workzones Work Zones
skip_days_for_stats Working days left for reported data to start impacting duration estimations
total Total
Available Fields for "partsCatalogItem" Entity Collection
This table provides the available fields for the ‘partsCatalogItem’ entity collection:
Field Example Value Description Mandatory
catalogId 17 A unique identifier of a catalog which contains the item.

Is returned by the getPartsCatalogsStructure procedure and is required by getParts procedure.

Yes
label a5123-df A unique identifier of a part within a catalog.

Is required by getParts procedure.

 Yes

Available Fields for "user" Entity Collection

This table provides the available fields for the ‘user’ entity collection:
Field Type Example Value Description
allow_desktop_notifications Number 0 1 - Browser desktop notifications are allowed,0 - disallowed
allow_vibration Number 0 1 - Vibration on mobile devices is allowed,0 - disallowed
design_theme Number 1 Design theme ID
format Object<String, String>

{

"date": "m/d/y",

"long_date": "l, F jS, Y",

"time": "h:i A",

"datetime": "m/d/y h:i A"

}

 Collection of date format strings in the PHP's style
main_resource_id (optional) 
Number
 1111 Resource ID which is set as main resource
providers Array<Number> [ 38, 3000001 ] List of resources, that are visible to user, excluding their descendants
sound_theme Number 0 Sound notification settings.0 - Off, 1 - Quiet, 2 - Loud, 3 - Persistent
su_zid Number 2 Time Zone id
uid Number 
2315
 Internal id of user
ulanguage Number 1 Language id (1 - English)
ulogin String admin Login
uname String Admin Name
week_start Number 0

Week start day (0-6).

0 - Sunday, 1 - Monday

Available Fields for "team" Entity Collection

This table provides the available fields for the ‘team’ entity collection:
Field Description
assistingTo

Object with resources to assist (each item is an array with other resources who assists)
assistingMe

Array with IDs of assistants
teamMembers

Object as plain collection with information about assistants. The information consists of the following four fields:

  • external_id
  • pactive
  • pname
  • uid