プラグインからフォームを開く

リリース26Aでは、Oracle Fusion Field ServiceプラグインAPIが拡張され、コア・フィールド・サービス・フォームをカスタム・プラグイン内で直接開いて管理できます。 Oracle Fusion Field Serviceソリューションに変更を適用するための新しいプロセスにより、開発作業が軽減され、プラグインUIページを再構築または再デプロイする必要がなくなり、モバイル・ワーカー・ワークフローの変更が加速されます。次のことができるようになりました。

リソース、アクティビティまたは在庫のプラグインからフォームを開く
パラメータを使用したフォーム・データの事前入力
オンラインおよびオフラインでの作業
フォームの下書きをリストアおよび復元
送信済フォームの問合せおよびオープン
「フォームとプラグイン」ページのユーザー・インタフェースの改善

リソース、アクティビティまたはインベントリのフォームを開く
プラグインAPIのcloseメソッドを使用して、フォームを開くか、アクションを実行します。この手順を使用する場合は、次のパラメータを指定する必要があります。

パラメータ表

パラメータ	説明	ノート
backScreen	戻るページ	常に"open_form"である必要があります。
backFormLabel	開くフォームのラベル	特定のフォームをターゲットにする場合は必須です。
backActivityID	特定のアクティビティのフォームをオープンする場合のアクティビティID	コンテキストがアクティビティの場合に使用します。
backInventoryID	特定の在庫のフォームをオープンする場合の在庫ID	コンテキストがインベントリの場合に使用します。
BackResourceID	特定のリソースのフォームをオープンする場合のリソースID	コンテキストがリソースである場合に使用します。
backFormParams	フォーム・フィールドを事前入力するためのキーと値のペア	フォーム入力の事前入力に使用されます。

例: closeメソッド

{

    "apiVersion": 1,

    "method": "close",

    "backScreen": "open_form",

    "backFormLabel": "some_form_label",

    "backActivityId": 1111,

    "backInventoryId": 1111, 

    "backFormParams": {

        "activity.some_property": "predefined_value"

 }

}

ノート: backActivityId、backInventoryIdまたはbackResourceIdパラメータを空白のままにすると、リソースのフォームがオープンされます。

フォームにデータを事前入力

プラグインAPIを使用してフォームを開く場合、backFormParamsを使用して、フォームが開いたときにフィールドのデフォルト値を設定できます。 backFormParamsパラメータの構文は、フォームで使用可能なデフォルトおよび検証ルールと同じです。 {entity}.field_labelという形式でフィールドを定義し、その値を追加できます。
プラグインAPIに、アクティビティまたは在庫詳細で使用される「パラメータ」ボタンと同じ機能が含まれるようになりました。

フォームのデータの事前入力

オンラインおよびオフラインでの作業

アプリケーションでは、オンライン・モードとオフライン・モードの両方でプラグインからフォームを開くことがサポートされています。
ただし、オフラインで使用するフォームを定義するために追加の構成が必要になる場合があります。「オフライン・プラグインのフォームの定義」を参照してください。

フォーム・ドラフトの操作
ドラフトのリストの取得
プラグインAPIの新しいgetFormDrafts プロシージャを使用すると、プラグインは、モバイル・ワーカーが保存したフォーム・ドラフトのリストを取得して、さらに使用することができます。
プロシージャには入力パラメータがないため、「現状のまま」使用する必要があります。

レスポンス

保存された下書きのリストを返します。各品目には、次の構成があります。

レスポンス

シリアル番号	名前	タイプ	説明
1	draftId	文字列	フォーム下書きの一意識別子
2	submittedAt	文字列	フォーム草案が送信された日時(ユーザーの書式)
3	formLabel	文字列	フォームの短いテキスト・ラベル
4	formTitle	文字列	ユーザーに表示されるフォームのフル・タイトル(ユーザーの言語)
5	userName	文字列	フォーム下書きを送信したユーザーの名前
6	activityId	文字列\| NULL	フォームがアクティビティに対して発行された場合にアクティビティIDを指定します
7	inventoryId	文字列\| NULL	フォームが在庫に対して発行された場合に在庫IDを指定します

フォームを開いたときに下書きを復元

新しいrestore_form_draftモードが、フォームを開くときにドラフトをリストアするCloseメソッド用に導入されました。これにより、フォームをオープンし、ユーザーが以前に保存したドラフトを自動的に復元できます。

下書きの復元

S. いいえ	名前	タイプ	必須	説明
1	draftId	文字列	はい	フォーム草案の一意識別子
2	backFormLabel	文字列	はい	フォームの短いテキスト・ラベル
3	backActivityId	文字列	いいえ	フォーム・ページのアクティビティを指定します
4	backInventoryId	文字列	いいえ	フォーム・ページのインベントリを指定します

送信済フォームのリストの取得
新しいgetSubmittedFormsプロシージャを使用すると、現在の営業日に送信されたフォームをプラグインで問い合せることができます。このプロシージャは、activityId、inventoryId、resourceInternalIdおよびformLabelのオプション・フィールドの任意の組合せに基づいて、送信されたフォームをフィルタします。

入力パラメータ(procedureData.params):

シリアル番号	名前	タイプ	説明
1	resourceInternalId	文字列	フォーム・ページのリソースを指定します
2	activityId	文字列	フォーム・ページのアクティビティを指定します
3	inventoryId	文字列	フォーム・ページのインベントリを指定します
4	formLabel	文字列	フォーム・ラベルを指定します

レスポンス
指定されたパラメータに従ってフィルタされた送信済フォームのリストを返します。各品目には、次の構成があります。

送信済フォームのリスト

S. いいえ	名前	タイプ	説明
1	formSubmitId	文字列	フォーム提出の一意識別子
2	submittedAt	文字列	フォームが送信された日時(ユーザーのロケール)
3	formLabel	文字列	フォームの短いテキスト・ラベル
4	formTitle	文字列	ユーザーに表示されるフォームのフル・タイトル(ユーザーの言語)
5	userName	文字列	フォームを送信したユーザーの名前
6	resourceInternalId	文字列	フォーム・ページのリソースを指定します
7	activityId	文字列\| NULL	フォーム・ページのアクティビティを指定します
8	inventoryId	文字列\| NULL	フォーム・ページのインベントリを指定します

特定のフォーム送信を開く
open_form_submitモードは、プラグインから特定のフォーム送信を開くための「閉じる」メソッド用に導入されています。

特定のフォーム送信

名前	タイプ	説明
backFormSubmitId	文字列	フォーム提出の一意識別子

オフライン・プラグインのフォームの定義

オフラインで使用するためにフォームをキャッシュする既存のメソッドに加えて、この機能により、フォームをオフラインで使用できるようにするための別のメカニズムが追加されます。現在のメソッドは、ボタンまたはワークフロー・ステップとして構成されたすべてのフォームをアプリケーションがキャッシュすることを意味します。 Hoveverは、プラグイン内でフォームを使用する場合、システム・インテグレータはボタンやステップなどのフォームを構成しません。そのため、オフライン・プラグインの機能を有効にするために新しいアプローチが確実に必要になります。フォームを追加または変更すると、オフラインで使用するためにフォームをキャッシュする組織およびユーザー・タイプを選択できます。この構成に続いて、選択した組織/ユーザー・タイプに属するすべての技術者のフォームがキャッシュされ、オフラインで使用できるようになります。組織/ユーザー・タイプが選択されていない場合、オフラインで使用するためにフォームをキャッシュする新しいアプローチは適用されません。

オフライン・プラグインのフォーム

ユーザーと組織の選択

「Forms & Plugins」ページの改善
ページが改善され、フォームとプラグインの両方についてすべての重要なパラメータが一貫して表示されます。

より明確な可視性のための3列のレイアウト
オフライン・キャッシュが構成されているフォームの「オフライン・キャッシュ: 有効」インジケータ
2番目の列に移動された構成済ボタン数
ボタンが構成されている特定のページを表示する新しいアイコン: 「ボタン構成済」
ボタン構成済アイコン
最新の構成変更を追跡するためにプラグインに追加された更新済およびユーザー・メタデータ

フォームとプラグインのページ

ノート:一部のプラグインでは、ユーザーに関するデータおよび26A更新直後の更新日が表示されない場合があります。これらのプラグインには、「次回の構成変更後に最終更新に関する情報が表示されます」というメッセージが表示されます。

ビジネス上の利点

プラグインを使用するユーザーのサービス・コストを削減し、プラグイン・ページへの頻繁な更新が必要
オンデマンドで、いつでも、ビジネスでページを変更する機能
フォームの組込み機能を使用した、従業員への変更の即時提供

有効化および構成ステップ

この機能を有効化するうえで必要な操作はありません。

ヒントと考慮事項

次に、プラグインAPIコールを最適に使用する方法を説明するユース・ケースについて説明します。
ユースケース

モバイル・ワーカーは、プラグインを使用してMyRouteページからアクティビティを開始します。
プラグインは、開始されたアクティビティの「アクティビティ詳細」を開きます
モバイルワーカーが「アクティビティ詳細」からプラグインを開き、次の作業を続行します
モバイルワーカーは、Ciscoビデオ会議、コピーマシン、モニターなどのアセットをインストールします。
モバイル・ワーカーが「マシンのコピー」の「資産検証」フォームをオープンし、フォームに入力して送信します
モバイルワーカーが'Cisco video conferencing'の'Asset inspection'フォームを開き、いくつかのデータを入力しますが、'Draft'の作成フォームから移動します。
モバイル・ワーカーが「資産検査」フォームを再度開き、フォームがドラフトから自動的に復元されます
モバイル・ワーカーが「資産検査」フォームを発行します
プラグインは、発行された「資産検証」および「資産検査」フォームへの参照を示します
モバイル・ワーカーが「Asset Validation(資産検証)」フォームを開き、フォームに正しく入力されていることを確認します。

アクティビティおよび在庫の検出
フォームを操作する前に、プラグインはどのアクティビティおよび在庫で動作するかを知る必要があります。この情報は、プラグインの起動時にpostMessageを使用して送信される「open」メッセージを介してホスト・アプリケーションによって提供されます。
このメッセージのペイロードには、2つのキー配列が含まれています。

activityList - 一意のIDおよびプロパティを持つアクティビティのリスト
inventoryList - インベントリとそのIDおよびプロパティのリスト

これらのデータにより、プラグインは後続の操作のためのリソースを識別できます。

Example: postMessage

 
{
    "apiVersion": 1,
    "method": "open",
    "entity": "activityList",
    "environment": {
        ...
    },
    "user": {
        ...
    },
    "resource": {
        "pactive": 1,
        "pid": 18370,
        "currentTime": "2025-09-04 08:23:47",
        "deviceUTCDiffSeconds": 1,
        "timeZoneDiffSeconds": -14400
    },
    "team": {
        "teamMembers": {},
        "assistingTo": {},
        "assistingMe": []
    },
    "queue": {
        "date": "2025-09-04",
        "status": "activated",
        "isActual": true,
        "activationTime": "2025-09-04 08:07:00"
    },
    "activityList": {
        "8769614": {
            "position_in_route": 1,
            "astatus": "pending",
            "aid": "8769614",
            "temporary_aid": "17569852170-3393"
        },
        "8769615": {
            "position_in_route": 2,
            "astatus": "pending",
            "aid": "8769615",
            "temporary_aid": "17569870070-7294"
        },
        "8769616": {
            "position_in_route": 3,
            "astatus": "pending",
            "aid": "8769616",
            "temporary_aid": "17569870300-7209"
        }
    },
    "inventoryList": {
        "26030118": {
            "inv_aid": null,
            "invtype": "Cisco video conferensing",
            "quantity": 1,
            "invsn": "123",
            "invpool": "provider",
            "invid": "26030118",
            "string_text_inventory_property": null,
            "inv_pid": 18370
        },
        "26030119": {
            "inv_aid": null,
            "invtype": "Copy machine",
            "quantity": 1,
            "invsn": "222",
            "invpool": "provider",
            "invid": "26030119",
            "string_text_inventory_property": null,
            "inv_pid": 18370
        },
        "26030120": {
            "inv_aid": null,
            "invtype": "Monitor",
            "quantity": 1,
            "invsn": "333",
            "invpool": "provider",
            "invid": "26030120",
            "string_text_inventory_property": null,
            "inv_pid": 18370
        }
    },
    "buttonId": "1215575",
    "openParams": {},
    "allowedProcedures": {
        "openLink": true,
        "searchParts": true,
        "searchPartsContinue": true,
        "getParts": true,
        "getPartsCatalogsStructure": true,
        "print": true,
        "share": true,
        "updateIconData": true,
        "updateButtonsIconData": true,
        "getAccessToken": true,
        "getAuthorizationCode": true,
        "getSubmittedForms": true,
        "getFormDrafts": true
    }
}

追加プロパティの構成
プラグインが必須フィールド(position_in_route、astatusなど)を確実に受信するには、次の場所で構成する必要があります。
「フォームとプラグイン」→「プラグインの編集」→「追加プロパティ」。

開始するアクティビティの選択
モバイル・ワーカーがMyRouteページに移動してプラグインを開くと、ホスト・アプリケーションにはペイロード内のすべてのアクティビティが含まれます。プラグインは、どのアクティビティを開始するかを決定できます。

activityListを調べます。
astatusでアクティビティをフィルタ: "pending"
position_in_route値が最小のアクティビティを選択します
プラグインAPI(「close」メソッド)を使用して、このアクティビティの開始をトリガーします

例: closeメソッド

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

アセットのインストール
モバイル・ワーカーが「アクティビティ詳細」ページからプラグインを開くと、ワークフローは必要なアセットのインストールを続行します。次に例を示します:

Ciscoビデオ会議
コピー機
モニター

続行するには、プラグインはpostMessageからのデータに依存します。 inventoryListペイロードには、使用可能なすべてのインベントリが含まれており、それぞれに一意のinvidがあります。
プラグインは次を実行します。

inventoryListを調べます。
必要なアセットをそのプロパティ(名前やタイプなど)で検索します。
対応するinvid値の取得
プラグインAPIをトリガーして、各アセットのインストールを登録します

複数のアセットをインストールする必要があるため、プラグインAPI("close"メソッド)はinvidごとに個別に呼び出されます。

例: closeメソッド
{ "apiVersion": 1, "method": "close", "backScreen": "install_inventory", "backActivityId": "8769614", "backInventoryId": "26030118" }
アセット検証- 送信
モバイル・ワーカーは、プラグインAPI (closeメソッド)を使用して'Copy machine'のアセット検証フォームを開きます。
例: closeメソッド

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

モバイル・ワーカーは、必要なデータを入力し、フォームを送信します。
ホスト・アプリケーションはフォームを完了として保存します。
アセット検査- ドラフトの作成
モバイル・ワーカーは、プラグインAPI (closeメソッド)を使用して、Ciscoビデオ会議のアセット検査フォームを開きます。
例: closeメソッド

{
    "apiVersion": 1,
    "method": "close",
    "backScreen": "open_form",
    "backFormLabel": "Asset_inspection",
    "backActivityId": "8769614",
    "backInventoryId": "26030118"
}

モバイル・ワーカーは、なんらかのデータを入力し、移動します。ホスト・アプリケーションは、フォームをドラフトとして保存します。

資産検査- 復元および発行
モバイル・ワーカーは、「資産検査」フォームを再度開きます。
フォームは既存の下書きから自動的に復元されます。
これを処理するために、プラグインはまずgetFormDraftsプロシージャをコールしてドラフトのリストを取得します。

例: callProcedureメッセージ

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

Example: callProcedureResult message

{
    "apiVersion": 1,
    "method": "callProcedureResult",
    "callId": "83yhtExpHwfo3eOwpOdinQ",
    "procedure": "getFormDrafts",
    "resultData": [
        {
            "draftId": "%7B%22p%22%3A%7B%22m%22%3A%22form%22%2C%22label%22%3A%22Asset_inspection%22%2C%22invid%22%3A%2226030118%22%2C%22a%22%3A%22form%22%7D%2C%22uid%22%3A1761%7D",
            "activityId": "8769614",
            "inventoryId": "26030118",
            "formLabel": "Asset_inspection",
            "formTitle": "Asset inspection",
            "submittedAt": "09/04/25 10:23",
            "userName": "BRC.ROOT"
        }
    ]
}

ドラフトの詳細を取得した後、プラグインはプラグインAPI (closeメソッド)を起動し、draftId、activityId、inventoryIdおよびformLabelを渡します。
これにより、フォームが下書きから復元され、モバイル・ワーカーがフォームを送信できるようになります。

例: closeメソッド

{
    "apiVersion": 1,
    "method": "close",
    "backScreen": "restore_form_draft",
    "backFormLabel": "Asset_inspection",
    "backActivityId": "8769614",
    "backInventoryId": "26030118",
    "backDraftId": "%7B%22p%22%3A%7B%22m%22%3A%22form%22%2C%22label%22%3A%22Asset_inspection%22%2C%22invid%22%3A%2226030118%22%2C%22a%22%3A%22form%22%7D%2C%22uid%22%3A1761%7D"
}

発行済フォーム- 参照
プラグインには、発行済資産検証フォームおよび資産検査フォームへの参照が表示されます。
この情報を取得するために、プラグインはgetSubmittedFormsプロシージャをコールします。

例: callProcedureメッセージ

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

Example: callProcedureResult message

{
    "apiVersion": 1,
    "method": "callProcedureResult",
    "callId": "HRW9sTJ1dmHkBvmaRWP8Eg",
    "procedure": "getSubmittedForms",
    "resultData": [
        {
            "formSubmitId": "135",
            "submittedAt": "09/04/25 11:03",
            "formLabel": "Asset_validation",
            "formTitle": "Asset validation",
            "userName": "BRC.ROOT",
            "resourceInternalId": "18370",
            "activityId": "8769614",
            "inventoryId": "26030119"
        },
        {
            "formSubmitId": "136",
            "submittedAt": "09/04/25 11:03",
            "formLabel": "Asset_inspection",
            "formTitle": "Asset inspection",
            "userName": "BRC.ROOT",
            "resourceInternalId": "18370",
            "activityId": "8769614",
            "inventoryId": "26030118"
        }
    ]
}

アセット検証- 送信済フォームのレビュー
モバイル・ワーカーは、アセット検証フォームを開いて、正しく入力されたことを確認します。
発行済フォーム・プロシージャから取得したformSubmitIdを使用して、プラグインAPI (closeメソッド)を使用して目的の発行を開きます。

例: closeメソッド

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