How do I use the open method in the Plug-In API?
When a user opens a plugin through a button, a message with the open method is sent to the plugin after Oracle Fusion 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 Fusion 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 plugin is opened from the Main menu. The response of the 'open' method is extended with the activity and inventory lists when they are available.
{
"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"
}
}
}{
"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
]
}
}{
"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"
}
}
}"team": {
"assistingTo": {},
"assistingMe": [],
"teamMembers": {}
}"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
| Page | Entity Field Value | Available Collections |
|---|---|---|
| Main menu Team Map |
user | user |
| Activity List Route Map |
activitiyList | user team queue resourceactivitiyList inventoryList |
| Activity List -> Inventory List | inventoryList | |
| Activity List -> Activity Details | activity | user team queue resourceactivityList activity inventoryList |
| Activity List -> Activity Details -> Inventory List | activityInventoryList | |
| Activity List -> Inventory List -> Inventory Details | inventory | user team queue resourceactivitiyList inventoryList inventory |
| Activity List -> Activity Details -> Inventory List -> Inventory Details | activityInventory | user team queue resourceactivityList activity inventoryList inventory |
| Inventory Search -> Parts Catalog Item Details | partsCatalogItem | user team queue resourceactivitiyList inventoryList partsCatalogItem |
- 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 Fusion 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 Fusion Field Service Core Application and opens the plugin
-
partsCatalogItem: Information that identifies the parts catalog item, so it can be retrieved using the getParts procedure
Availability of activity, inventory, and resource properties depends on the configuration of the plugin. See Available Properties for details.
Available Fields for '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> | |
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 |
| 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 | |
| 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 |
| 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.
{
"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
| 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 |
| Field | Description |
|---|---|
| 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 plugin 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. |
| 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 |
| 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
| 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
| 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:
|