メッセージング API - アクション センター、メッセージ バー、メッセージ詳細
この記事では、財務と運用アプリのメッセージング システムについて、特にメッセージを作成してエンド ユーザーにルーティングするために使用されるアプリケーション プログラミング インターフェイス (API) の観点から、説明します。
概要
このエクスペリエンスを改善するために、財務と運用アプリ用に新しいメッセージング システムが作成されました。 以前のバージョンと比較すると、財務と運用アプリのメッセージング システムには次の機能が含まれています:
- コンテキストのあるメッセージの関連性が強化されました (フォームとグローバル)。
- 中断のレベル (なし、軽微、および中断) を強化しました。
- メッセージの種類間での明確さと、その用途が強化されました。
- メッセージを表示するために使用されるコントロールは、フォーム コンテキストに基づいて deterministic です。
Info()、warning()/checkfailed()、error() の下位互換性
以前のバージョンの財務と運用アプリからの info()、warning()、および error() のアプリケーション プログラミング インターフェイス (API) は引き続きサポートされますが、これらの API は現在、フレームワークの新しいメッセージング システム上にあります。 API呼び出しのコンテキストを使用して、ユーザーにメッセージを提示する最適な方法を決定することにより、メッセージは確定的にメッセージまたはアクション センター (中断しない方法で) にルーティングされます。 一般に、API の使用がフォームから生成された場合、そのメッセージが同じフォーム上のメッセージ バーで表示されます。 (ドロップ ダイアログとスライダ ダイアログは、どちらもフォームと見なされます。)
次の図は、ページ アクションに対応する 情報、警告/checkfailed、エラー メッセージ バー、または info()、warning()、error() からの同期作成メッセージを示しています。
メモ
スライダー ダイアログからこれらの API が呼び出されても、メッセージが表示される前にそのスライダー ダイアログが閉じられると、メッセージはスライダー ダイアログの親ページのメッセージ バーに表示されます。 メッセージが表示される前にそのスライダー ダイアログ ボックスが閉じられ、親ページが存在しない場合、メッセージは、アクション センターにルーティングされます。 メッセージング API は必ずメッセージを表示します。 適切なホスト ページが見つからない場合は、メッセージがアクション センターに送信されます。
info()、warning()/checkfailed()、または error() が非同期プロセス (たとえば、バッチ) から呼び出された場合、考慮するフォーム コンテキストはなく、メッセージはアクション センターに送信されます。 (アクション センターを開くには、ナビゲーションバーの メッセージを表示 ボタンをクリックします。) 次の図は、アクション センターの各種メッセージの例を示しています。
メモ
Box() API を使用して、ユーザーに中断エラーを表します。
SetPrefix() の下位互換性
財務と運用アプリは、下位互換性のために SetPrefix() API もサポートしています。 ただし、メッセージング システムでは、SetPrefix() の結果は、積極的にユーザーを中断しません; 代わりに、結果が (以前のバージョンと同様に) 収集および保存され、メッセージ バーまたはアクション センターの通知がユーザーに表示されます。 この通知は、関連するタスクが完了し、ユーザーが確認する必要のあるメッセージがある可能性があることを示します。 「結果の通知」メッセージは、実際にはタスクによる SetPrefix() の最初の呼び出しを使ってメッセージをフレーム化します。 この動作は、最初の呼び出しが結果の「タイトル」であった以前のバージョンの動作に類似しています。 この例では、「転記の結果」が SetPrefix() への最初の呼び出しのアプリケーションから取得されます。
ユーザーは、メッセージの詳細 をクリックして、新しい メッセージの詳細 ウィンドウを開くことができます。
Message()
メッセージ API には、いくつかの便利なメッセージング機能があります。 Message () API を使用すると、メッセージを明示的に追加および削除できるため、メッセージのライフサイクルをより詳細に制御できます。 この API は、保存境界を超えたとき以外に検証メッセージを削除する必要がある場合や、データ検証に必ずしも関連しないユーザー エクスペリエンスの側面に関する情報メッセージを表示する場合に役立ちます。 この例では、現在のレコードが表示されるときにメッセージは表示されます。
messageId = Message::Add(MessageSeverity::Informational, "The customer is marked as inactive");
新しいレコードがページに表示されると、メッセージはクリアされます。
Message::Remove(messageId);
バージョン 10.0.10 / Platform update 34 以降では、Message::AddAction() メソッドを使用して、メッセージ内にアクションを埋め込むことができます。 このメソッドは、表示メニュー項目またはアクション メニュー項目に関連付けられた 1 つのアクションの追加をサポートし、リンク ボタンとして視覚化されます。 アクションは、バージョン 10.0.16/Platform update 40 までメッセージ バーにルーティングされるメッセージでのみサポートされ、その時点でアクション センターまたはメッセージの詳細ウィンドウにルーティングされるメッセージに、これらのアクションが表示されます。
この例では、システム管理者に特定の必要なバッチ ジョブが実行されていないことを示すメッセージがトリガーされ、バッチ ジョブ ページに直接移動するアクションが表示されます。
MenuItemMessageAction actionData = new MenuItemMessageAction();
actionData.MenuItemName("BatchJob");
str jsonData = FormJsonSerializer::serializeClass(actionData);
int64 messageId = Message::AddAction(MessageSeverity::Informational, "The Test batch job is not currently running", "Go to Batch jobs", MessageActionType::DisplayMenuItem, jsonData);
以下のメッセージタイプがサポートされています: MessageSeverity::Info、MessageSeverity::Warning、および MessageSeverity::Error。 また、Message() API を使用するメッセージは確定的となります。 メッセージ バーまたはアクション センターにルーティングできます。
SystemNotificationsManager()
SystemNotificationsManager() クラスでは、アクション センターに通知を送信できます。 このクラスは、次の機能を提供します:
- 1 つ以上のアクションの通知への関連付け。
- 通知を一連のユーザー、または 1 つ以上のセキュリティ ロールのすべてのユーザーにルーティングする。
- 通知の有効期限の定義。
- 通知の状態の追跡 (通知に「完了」としてマークできるなど)。
- RuleID によって通知に適用されるルールまたはプロセスを定義する。
この例では、ユーザーが Excel へのエクスポートを完了した後に通知が発生します。 このメッセージは、エクスポートされたファイルへのリンクが使用できなくなるまで、アクション センターで今後 48 時間使用できるようになります。
メモ
AddNotification() API は、以前にこの例で使用されています。 バージョン 10.0.23 の場合、API は廃止され、AddSystemNotification() API に置き換えられる予定です。 新しい API は、RuleID と ExpirationDateTime の設定を要求します。
// Set up the notification
SystemNotificationDataContract notification = new SystemNotificationDataContract();
notification.Users().value(1, curUserId());
notification.Title("Export to Excel finished");
notification.RuleId('ExcelStaticExport');
notification.Message("We finished your export from the Customers page");
notification.ExpirationDateTime(DateTimeUtil::addHours(DateTimeUtil::utcNow(), 48));
// Set up the action associated with the notification
SystemNotificationActionDataContract action = new SystemNotificationActionDataContract();
action.Message("Click to download");
action.Type(SystemNotificationActionType::AxActionMenuFunction);
SystemNotificationMenuFunctionDataContract actionData = new SystemNotificationMenuFunctionDataContract();
actionData.MenuItemName(menuItemActionStr(ExportToExcelStaticOpenFileAction));
actionData.Data(fileName);
action.Data(FormJsonSerializer::serializeClass(actionData));
notification.Actions().value(1, action);
SystemNotificationsManager::AddSystemNotification(notification);