2021年4月24日土曜日

Flows for APEXを使ってみる - Flows for APEX 5.1.2版

Flows for APEXのバージョン21.1による記事もあります。

 ドイツのMT AGが提供しているOracle APEXの拡張機能、Flows for APEXを使ってみます。BPMN 2.0で記述したビジネス・プロセスをOracle APEXで実行させるツールです。ツールの詳細については、リンク先の説明を参照してください。

BPMNのダイアグラムの記述には、BPMN.io(Camunda Services GmbHが開発元)が提供しているBPMNエディタを使用しています。Camundaもドイツの会社で、BPM(ビジネス・プロセス・マネジメント)ツールの領域では一定の評価を得ているようです。

Flows for APEXのアーカイブをダウンロードすると、その中に休暇申請のサンプル・アプリケーションが含まれています。(今回はバージョン5.1.2を使っています)。そのサンプルと同じアプリケーションを手作業で作成することにより、使い方を理解します。

ダウンロードしたFlowsforAPEX_v5.1.2.zipには、以下の2つのOracle APEXアプリケーションが含まれています。

FLOWSFORAPEX_EN_APEX201_984339_UTF8_V5.1.2.sql

FLOWSFORAPEX512_INTEGRATION_DEMO_HOLIDAY_EN_APEX201_984341_UTF8_V2.0.sql

最初のファイルがFlows for APEXの本体です。BPMNによるダイアグラムを記述するアプリケーションとFlows for APEXを動かすために必要とされる、表などのデータベース・オブジェクトを作成します。

次のファイルがサンプルである休暇申請アプリケーションです。以下のフローを処理します。

休暇申請を作成し、承認または却下の処理をする、という単純なサンプルです。


アプリケーションのインポート

ZIPファイルに含まれているアプリケーションをインポートします。アプリケーション・ビルダーを開き、インポートを実行します。特別な作業はなく、通常のアプリケーションのインポート作業です。


最初にFlows for APEX本体となるアプリケーションをインポートします。ファイル・タイプとしてデータベース・アプリケーション、ページまたはコンポーネントのエクスポートを選択します。に進みます。32MB程度の大きさがあるので、インポートにも時間がかかります。


ファイルのインポートの確認を求められます。そのままに進みます。


アプリケーションのインストール画面になるので、新規アプリケーションIDを自動割当てを行う設定のまま、アプリケーションのインストールを実行します。


必ずサポートするオブジェクトのインストールONに設定し、に進みます。


インストールを実行します。


アプリケーションがインストールされます。インストール・サマリーを確認してみます。


表やビュー、パッケージなどもアプリケーションのインストールと同時に作成されています。作成されたデータベース・オブジェクトは先頭にFLOW_というプレフィックスが付けられています。


同様の手順で、サンプル・アプリケーションもインポートします。Flows for APEXHoliday Approval (demo app to show how to integrate flows for APEX)の2つのアプリケーションがインストールされました。


これから、Holiday Approvalと同じアプリケーションを作成していきます。

休暇申請アプリケーションの作成

休暇申請を保持する表を作成します。クイックSQLで以下のモデルを定義します。

# prefix: hap
# semantics: default
requests
emp_name vc100 /nn
start_date date /nn
end_date date /nn
is_approved vc1 /check Y,N

主キーである列IDの他に、従業員名(emp_name)、休暇の開始日(start_date)、終了日(end_date)、承認または却下のフラグ(is_approved)を定義します。

SQLの生成SQLスクリプトを保存、そして、レビューおよび実行を行い、表HAP_REQUESTSを作成します。


表が作成されたら、継続してアプリケーションの作成を実行します。


アプリケーションの作成をクリックします。


アプリケーションの名前休暇申請とします。デフォルトで表HAP_REUESTSに対する対話モード・レポートとフォームが作成されます。デフォルトのまま、アプリケーションの作成を実行します。


アプリケーションが作成されます。Flows for APEXのダイアグラムで扱うページ・アイテムを確認します。ページ番号3のフォームのページをページ・デザイナで開きます。


ページ・アイテムとしてP3_ID、 P3_EMP_NAME、 P3_START_DATE、 P3_END_DATE、 P3_IS_APPROVEDがあります。


後でBPMNのダイアグラムにタスクを作成します。そのタスクとしてAPEXのアプリケーションを設定しますが、そのときに使用する設定をアプリケーションに追加します。

最初にアプリケーション・アイテムとしてPROCESS_IDSUBFLOW_IDを登録します。共有コンポーネントアプリケーション・アイテムを開きます。


登録済みのアプリケーション・アイテムの一覧より、作成を実行します。


名前PROCESS_IDを指定し、セッション・ステート保護制限なしとします。アプリケーション・アイテムの作成を実行します。


同様にSUBFLOW_IDも作成します。


アプリケーション・アイテムとしてPROCESS_ID、SUBFLOW_IDが作成されています。


次にアプリケーション定義の画面を開き、アプリケーションの別名HOLIDAYREQに変更します。


インポートしたサンプル・アプリケーションより、アプリケーションに必要なプラグインを3つコピーします。共有コンポーネントプラグインを開きます。


プラグインの一覧画面より、作成を実行します。


プラグインの作成として、既存のプラグインのコピーを選択します。に進みます。


アプリケーションからコピーとして、Flows for APEXのサンプル・アプリケーションであるHoliday Approval (demo app to show how to integrate Flows for APEX)を選択します。に進みます。


3つのプラグインがリストされます。コピーしますか。コピーおよびサブスクライブはいのいずれかを選択します。今回は単に演習なので、元のプラグインの参照を残す必要はありません。はいを選択し、プラグインのコピーを実行します。


プラグインがコピーされます。


Oracle APEXのアプリケーションの事前準備はここまでとし、次にFlows for APEXのアプリケーションを使ってBPMNのダイアグラムを記述します。

休暇申請フローの記述


Flows for APEXを実行します。APEXのワークスペースにサインインするアカウントで、アプリケーションにサインインします。


アプリケーションが実行されると、最初にGetting Startedのページが開きます。フローの作成や編集をするときは、Flow Managementを開きます。本記事ではFlows for APEXの個々の操作方法自体の説明は省いていますので、それらについてはDocumentationを参照してください。


フローの定義画面が開きます。新規にフローを作成するため、右上のCreate Flowをクリックします。


CategoryMy DiagramNameHolidayRequestとし、Version1とします。Categoryは単にレポート上の分類なので、任意の名前を設定できます。NameとVersionはAPEXアプリケーションで使用します。Createをクリックします。


フローが新規に作成されます。Edit Flowをクリックして、フローの編集を行います。


パレット上のStartEventをクリックして選択し、キャンパス上の適当な位置でクリックすることで、キャンパスにStartEventを配置します。StartEventがフローの起点になります。


パレットからTaskをクリックし、StartEventの右隣に配置します。


Taskのスパナ・アイコンをクリックし、TaskのタイプUser Taskに設定します。User TaskはAPEXアプリケーションへのリンクであり、APEXのページ上でユーザーが操作を行うことを要求します。


Taskのタイプにはいくつか種類があり、APEXのアプリケーションの呼び出し以外にも、PL/SQLスクリプトの実行なども行うことができます。詳しくはマニュアルを参照してください。

作成したTaskを設定します。Generalの項目のIdActivity_Submit_Holidayとします。NameApprove Holidayとします。IdがTaskの識別子であり、Nameはフローのダイアグラム上の表示に使われます。


User Taskとして呼び出すAPEXのリンクを設定します。ApplicationHOLIDAYREQPage3Page ItemsにはP3_ID,PROCESS_ID,SUBFLOW_IDを指定し、Item Valuesとして&F4A$BUSINESS_REF.,&F4A$PROCESS_ID.,&F4A$SUBFLOW_ID.を指定します。APIのファンクションAPEX_PAGE.GET_URLに与える引数と同じです。&F4A$で始まるアイテムはFlows for APEXが予約しているアイテムになります。


パレットからGatewayをクリックし、Taskの右隣に配置します。GeneralIdGateway_Approvalとし、NameApproved?と設定します。


パレットからEndEventをクリックし、Gatewayの右隣に配置します。NameHoliday Approvedとします。


再度パレットからEndEventをクリックし、先程のHoliday ApprovedのEndEventの下に配置します。NameHoliday Rejectedとします。


今まで配置した要素を接続します。


Gateway_Holiday_Approval(Gateway)からHoliday Approval(EndEvent)への接続を選択し、IdYNameyesとします。承認されたときのパスです。


Gateway_Holiday_Approval(Gateway)からHoliday Rejected(EndEvent)への接続を選択し、IdNNamenoとします。却下されたときのパスです。


以上でダイアグラムが完成しました。Save Flowをクリックし保存します。


Cancelをクリックして元のページに戻り、Apply Changesをクリックします。


Cancelをクリックし、Flow Managementの画面に戻ります。NameHolidayRequestのフローが作成され、Flow Parsedチェックが入っていることを確認します。


以上でダイアグラムの作成が完了しました。

アプリケーションへのフローの組み込み


現在は表HAP_REQUESTSを対象とした、対話モード・レポートとフォームが作成されています。こちらにFlows for APEXで定義したBPMNのフローを、ワークフローとして組み込みます。

対話モード・レポートのソースにワークフローの処理経過も表示するよう、ソースを変更します。ソースタイプSQL問合せに変更し、以下のSQL問合せを設定します。Flows for APEXが提供するビューFLOW_TASK_INBOX_VWと表HAP_REQUESTSをジョインします。

select
h.id
, h.emp_name
, h.start_date
, h.end_date
, tibx.link_text -- ユーザー・タスクへのリンク (ページ3)
, tibx.sbfl_prcs_id -- フロー・ステータスの表示 (ページ4)
, tibx.sbfl_process_name -- リンク名
-- your table
from hap_requests h
-- provided by Flows for APEX
join flow_task_inbox_vw tibx on h.id = tibx.sbfl_business_ref


変更したらページを実行し、作成をクリックします。

このままでは単に表HAP_REQUESTSに行が挿入されるだけです。新規にデータを挿入すると同時に、ワークフローを開始するためのプロセスを作成します。開発者ツール・バーよりページの編集を実行します。


プロセスを作成します。フォーム処理の次に実行されるように配置します。名前は任意ですが、もともとのサンプル・アプリケーションと同じ名前であるFlows for APEX - Create/Startとします。タイプにFlows for APEXが提供しているプラグインFlows for APEX - Create and Start Flow[プラグイン]を選択します。設定Flow selection based onは、フロー(ダイアグラム)の名前とバージョンのセットで指定するよう、Name & Versionを選択します。Select Flow usingComponent Settingとし、コンポーネント設定としてフロー名とバージョンを指定します。Set Flow instance name usingStatic Assignmentとし、Static Text休暇申請 - &P3_EMP_NAME. - &P3_START_DATE.を指定します。これが開始したワークフローのインスタンス名になります。Set Business Referenceは主キーの値であるP3_IDSet add. process variablesNo Process VariablesStart Flow instance?ONにします。

サーバー側の条件として、ボタン押下時CREATEを設定します。


実行されるフローを指定するため、共有コンポーネントコンポーネント設定を開きます。


コンポーネント設定のFlows for APEX - Create and Start Flow [プラグイン]を開きます。


Global Flowに作成ずみのフロー名HolidayRequestとバージョン番号の1HolidayRequest,1として指定します。変更の適用をクリックします。


アプリケーションを実行し、休暇申請を作成します。Is Approvedに値は入れません。


休暇申請の行が表HAP_REQUESTSに挿入されると同時に、ワークフローも開始します。Link Textとして、Approve HolidayのUser Taskのリンクが表示されています。


このリンクをクリックしてページの実行ができるように、対話モード・レポートの列の定義を変更します。列LINK_TEXTを選択し、タイプリンクに変更します。ターゲットタイプURLURLとして#LINK_TEXT#を指定します。今回は学習のためにアプリケーションを作成しているので、リンク・テキスト#LINK_TEXT#のままにします。


変更した設定を保存し、ページを実行します。Link Textがリンクになるので、Link Textをクリックして休暇申請の承認または却下を行う画面を開きます。


Is ApprovedにYまたはNを入力し、変更の適用をクリックすることで、休暇申請の承認もしくは却下を行いますが、今はまだワークフローと連携できていません。開発者ツール・バーよりページ・デザイナを開き、新たにプロセスを作成します。

作成したプロセスの名前Flows for APEX - Complete Stepとします。タイプFlows for APEX - Complete Step[プラグイン]を選択します。設定Define Instance and Subflow ByPage Itemとし、Process Idはアプリケーション・アイテムよりPROCESS_IDSubflow Idもアプリケーション・アイテムよりSUBFLOW_IDを設定します。Define GatewayONにし、GatewayGateway_Approvedを指定します。Routeとして&P3_IS_APPROVED.を指定します。

サーバー側の条件として、ボタン押下時SAVEを設定します。


ワークフローでの承認と却下の処理が追加されたので、ページを実行して確認します。Is ApprovedYを入力し、変更の適用をクリックします。


ワークフローが終了したため、対話モード・レポートから行が消えました。


このままだと処理結果がわからないので、Flows for APEXのサンプルと同じく円グラフを追加します。対話モード・レポートがあるページをページ・デザイナで開き、チャートのリージョンを作成します。

新規にリージョンを作成し、名前Holiday Requestsとします。タイプチャートを選択します。


Attributesを開き、チャートタイプを選択します。


すでに作成されているシリーズを選択し、ソースタイプSQL問合せとし、SQL問合せに以下を設定します。

select
count(*)
, is_approved
from
(
select
id
, case
when is_approved = 'Y' then '承認'
when is_approved = 'N' then '却下'
else '処理待ち'
end is_approved
from hap_requests
)
group by is_approved

列のマッピングラベルIS_APPROVEDCOUNT(*)を選択します。


ページを実行し、円グラフが表示されることを確認します。


さらにフォームを閉じた時に円グラフも更新されるよう、動的アクションに変更を加えます。

ページ・デザイナを開き、左ペインに動的アクション・ビューを表示させます。すでにあるリフレッシュのアクション重複させ、リージョンを対話モード・レポートであるHap Requestsから、円グラフのリージョンであるHoliday Requestsに変更します。


ワークフローとの連携は以上で実装が完了しました。

この時点で、以下のような動作になります。


進捗確認画面の組み込み


Flows for APEXが提供しているもう一つのプラグイン、MTAG BPMN Viewerを組み込んでみます。ワークフローの進捗を確認することができるようになります。

進捗を表示するページを作成します。ページの作成を実行し、空白ページを選択します。


名前Flow Statusとし、ページ・モードとしてモーダル・ダイアログを選択します。に進みます。


ナビゲーションのプリファレンスとして、このページとナビゲーション・メニュー・エントリを関連付けないを選択します。に進みます。


終了をクリックすると、空白ページが作成されます。


ページが作成されたら、新規にリージョンの作成を行います。

識別タイトルFlow Statusとし、タイプMTAG BPMN Viewer[プラグイン]を選択します。表名FLOW_INSTANCE_DETAILS_VWを選択し(ビューとして選択する)、WHERE句prcs_id = :PROCESS_IDを指定します。


続いてリージョンのAttributesを開き、ビューワーに対する設定を行います。設定する内容は以下になります。

Diagram XML: DGRM_CONTENT
Add Highlighting: ON
Current Marker: ALL_CURRENT
Currents Separator: : (コロン)
Completed Marker: ALL_COMPLETED
Completed Separator: : (コロン)
Last Completed Marker: LAST_COMPLETED
Last Completed Separator: : (コロン)
Refresh On Load: ON
Enable SubProcess expand/collapse: ON
Enabled Viewer Navigation: OFF


これで進捗を表示する画面ができました。対話モード・レポートからリンクするため、対話モード・レポートのページをページ・デザイナで開きます。

SBFL_PRCS_IDを選択し、タイプリンクに変更します。


ターゲットを設定します。ページにはFlow Statusとして作成したページのページ番号を選択し、アイテムの設定として名前PROCESS_ID#SBFL_PRCS_ID#を指定します。OKをクリックします。


以上で進捗の確認画面も作成できました。アプリケーションを実行して確認すると、以下のような動作になります。


以上でFlows for APEXを組み込んだアプリケーションは完成です。

今まで勉強しよう、しようと思っていたのですが、難しそうで敬遠していました。また、マニュアルが英語なのもありますが、いくら読んでも、アプリケーションの作り方が分かりませんでした。

今回、簡単なサンプルですが、いちからアプリケーションを作ってみて、なんとか始められるようになりました。時間を見つけて、もっと使い方を理解したい機能のひとつです。

今回、作成したアプリケーションをエクポートしたファイルを以下に置きました。Flows for APEXに添付のサンプルと基本的には同じです。
https://github.com/ujnak/apexapps/blob/master/exports/holidayrequest.sql

Oracle APEXのアプリケーション作成の参考になれば幸いです。