Form Integration Using Plugin API

Oracle Fusion Field Service plugins can integrate seamlessly with forms using the Plugin API, enabling dynamic workflows for mobile workers with minimal custom coding. This section outlines best practices through a detailed use case: asset installation with form handling.

Key Concepts

• Use the initial open message payload to identify activities and inventories.
• Trigger actions using targeted close method calls.
• Configure Additional Properties to ensure required fields (such as, position_in_route, astatus) are available.
• Minimize redundant API calls for efficient online and offline workflows.

Use Case: Asset Installation Workflow

A mobile worker installs three assets: a Cisco video conferencing unit, a copy machine, and a monitor. The workflow includes:

• Starting the activity
• Installing assets
• Validating and inspecting assets using forms
• Handling drafts and submissions
• Reviewing completed forms

Step-by-Step Workflow

1. Launch Plugin and Discover Context

When the plugin is opened from the My Route page, the host sends an open message with activityList and inventoryList.

• Filter activityList by astatus: pending and select the lowest position_in_route.
• Match assets in inventoryList using invtype or invsn.
• Use aid and invid for subsequent operations.

2. Start the Activity

The plugin identifies the first pending activity and triggers its start. This navigates to the Activity Details page automatically.

{
  "apiVersion": 1,
  "method": "close",
  "backScreen": "start_activity",
  "backActivityId": "8769614"
}

3. Install Assets

From Activity Details, the mobile worker reopens the plugin. Using the inventoryList from the "open" payload, the plugin locates assets by properties. For example, invtype: "Copy machine" for ID 26030119.

Invoke separate "close" calls for each installation to register them one by one. This ensures sequential processing and error handling.

{
  "apiVersion": 1,
  "method": "close",
  "backScreen": "install_inventory",
  "backActivityId": "8769614",
  "backInventoryId": "26030118"
}

4. Open and Submit Validation Form

After installation, open the "Asset Validation" form for the copy machine (ID
          26030119). The mobile worker fills and submits it, saving as
      completed.

{
  "apiVersion": 1,
  "method": "close",
  "backScreen": "open_form",
  "backFormLabel": "Asset_validation",
  "backActivityId": "8769614",
  "backInventoryId": "26030119"
}

5. Create and Restore Drafts

Open the "Asset Inspection" form for the Cisco unit (ID 26030118). The mobile worker enters partial data and navigates away, auto-saving as a draft.

Later, to resume: Call getFormDrafts to list drafts, then restore the matching one.

Call to get drafts:

{
  "apiVersion": 1,
  "method": "callProcedure",
  "callId": "83yhtExpHwfo3eOwpOdinQ",
  "procedure": "getFormDrafts",
  "params": {}
}

Restore a draft:

{
  "apiVersion": 1,
  "method": "close",
  "backScreen": "restore_form_draft",
  "backFormLabel": "Asset_inspection",
  "backActivityId": "8769614",
  "backInventoryId": "26030118",
  "backDraftId": "<encoded_draft_id>"
}

6. Reference Submitted Forms

The plugin queries submissions for the activity to display links (for example., to "Asset Validation" and "Asset Inspection"). Use getSubmittedForms with filters like activityId.

Call to get submissions:

{
  "apiVersion": 1,
  "method": "callProcedure",
  "callId": "uniqueId",
  "procedure": "getSubmittedForms",
  "params": {
    "formLabel": "",
    "resourceInternalId": "",
    "activityId": "",
    "inventoryId": ""
  }
}

7. Review Submitted Form

To verify the "Asset Validation" form, use the formSubmitId (for example., "135") to open it as read-only.

{
  "apiVersion": 1,
  "method": "close",
  "backScreen": "open_form_submit",
  "backFormSubmitId": "135"
}
            

Best Practices

• Configure Additional Properties to include required fields.
• Queue installations to avoid overwhelming the host.
• Use backFormParams to pre-fill forms.
• Always check for drafts before opening forms.
• Limit submission queries to the current business day.