2022年12月16日金曜日

Flows for APEXによる休暇申請フローの作成(3) - APEXアプリケーションの作成

 休暇申請のワークフローを処理するAPEXアプリケーションを作成します。


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



休暇申請を保持する表を作成します。クイックSQLの以下のモデルより、表HAP_REQUESTSを作成します。
# prefix: hap
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を開きます。左側に上記のクイックSQLのモデルを記述し、SQLの生成SQLスクリプトの保存と続けて、レビューおよび実行を行います。


以下の画面ではアプリケーションの作成ではなく、実行をクリックします。


この後に表示されるダイアログにて、DDLの即時実行を行います。表HAP_REQUESTSが作成されたことを確認し、アプリケーションの作成を実行します。確認画面が表示されるので、そこでもアプリケーションの作成をクリックします。


アプリケーション作成ウィザードが起動します。

アプリケーションの名前休暇申請とします。デフォルトで表HAP_REQUESTSをソースとする対話モード・レポートフォームのページが作成されます。ホーム画面は不要なので編集をクリックして削除します。

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


アプリケーションが作成されました。ワークフローの処理を組み込む前に、いくつか準備をします。

アプリケーション定義の編集をクリックします。


アプリケーションの別名を休暇申請から、フロー・モデルで使用しているHOLIDAYREQに変更します。変更の適用をクリックします。


ページ番号2として作成されているフォームのページRequestを、休暇申請のフロー・モデルのユーザータスクとして定義しているAPEXページにします。

ページ・デザイナにて、ページ番号Requestを開きます。

識別別名ユーザータスクページIDとして設定したrequestになっていることを確認します。


APEXアプリケーションがフロー・モデルよりも先に作成されていると、フロー・モデルを作成する際にAPEXメタデータを使用することができます。


以上でワークフローを実装するAPEXアプリケーションの作成は完了です。

次の記事では、このアプリケーションにワークフローの処理を組み込みます。

続く

Flows for APEXによる休暇申請フローの作成(2) - フロー・モデルの作成

Flows for APEXが提供しているワークフローのモデラーを使用して、休暇申請のフロー・モデルを作成します。 


休暇申請のフロー・モデルの作成



ワークスペースにインストールされたアプリケーションFlows for APEXを実行します。


APEXワークスペースのサインインに使用したユーザー名パスワードにてFlows for APEXのアプリケーションにサインインします。

Flows for APEX 22.2より言語として日本語を選択できます。


アプリケーションにサインインすると、利用状況を表示するダッシュボードのページが表示されます。フロー・モデルの作成や編集をするには、フロー管理を開きます。


フロー・モデルの管理画面が開きます。新規にフロー・モデルを作成するには、右上のモデルの作成をクリックします。


新規に作成するモデルの属性カテゴリー社内手続きとします。モデルの名前休暇申請バージョン0を指定します。カテゴリーは単に表示の際に使用される分類なので、任意の名前を設定できます。名前バージョンはAPEXアプリケーションで使用します。

作成をクリックします。


新規にフロー・モデルが作成されます。ダイアグラム変更をクリックし、フロー・ダイアグラムの編集を行います。


パレットにある開始イベントをキャンパスにドラッグ&ドロップします。開始イベントがフローの起点になります。パレット上の開始イベントをクリックして選択し、キャンパスの任意の位置をクリックして配置することもできます。


開始イベントの右隣にタスクを配置します。


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


タスクの属性を設定します。一般のグループを開き、名前休暇申請の承認とします。タスク・タイプのグループを開き、タスク・タイプとしてAPEXページを選択します。

タスク・タイプとしてAPEXページまたはAPEXの承認を選択できます。APEXページはAPEXアプリケーションのページでの操作がタスクになります。APEXの承認はAPEX 22.1から新規に提供されている承認コンポーネントでの操作がタスクになります。


ユーザータスクとして呼び出すAPEXページを設定します。

APEXページのグループを開きます。まだAPEXアプリケーションは作成していないため、APEXメタデータの使用オフにします。

アプリケーションIDHOLIDAYREQページIDrequestとします。これらはAPEXのアプリケーションを作成するときに、アプリケーションの別名およびページの別名として指定します。


Page Itemsを設定します。最初にデフォルト・アイテムの作成をクリックします。アイテム名PROCESS_IDとアイテム値&F4A$PROCESS_ID.のペア、SUBFLOW_ID&F4A$SUBFLOW_ID.STEP_KEY&F4A$STEP_KEY.のペアが作成されます。

F4A$で始まるアイテム(置換文字列として指定されているため&.で囲まれています)は、Flows for APEX(F4A)によって予約されているアイテムになります。


Page Items横の(プラス)サインをクリックし、ページ・アイテムの設定を追加します。

アイテム名P2_IDアイテム値として&F4A$BUSINESS_REF.を指定します。&F4A$BUSINESS_REF.にはフロー・モデルから生成されるプロセス・インスタンスを特定するキーとなる値を設定します。一般にこれは表の主キーの値になります。ページ・アイテムP2_IDには、フォームで操作する表の主キーの値が設定されます。


変更の適用をクリックすると、今まで行った変更がデータベースに保存されます。


パレットからゲートウェイを選択し、タスク休暇申請の承認の右隣に配置します。名前承認?とします。


パレットから終了イベントを選択し、ゲートウェイ承認?の右隣に配置します。名前休暇承認とします。


再度パレットから終了イベントを選択し、先ほど作成した終了イベント休暇承認の下に配置します。名前休暇却下とします。


今まで配置した要素をシーケンスフローで接続します。グローバルコネクトツールをクリックした後、始点終点となる要素を続けてクリックし、それぞれの要素を接続します。


ゲートウェイ承認?から終了イベント休暇承認へのシーケンスフローを選択します。名前はいとします。

条件条件タイプとしてを選択し、条件として以下を設定します。

:F4A$IS_APPROVED = 'Y'

ゲートウェイ承認?にフローが進んだ時点で、プロセス変数IS_APPROVEDYだったときに、このシーケンスフローが選択されます。


ゲートウェイ承認?から終了イベント休暇却下へのシーケンスフローを選択します。名前いいえとします。


表示されているスパナ・アイコンをクリックし、ディフォルトフローを選択します。


デフォルトのフローには斜線が表示されます。


終了イベント休暇承認へのフローが選択される条件(F4A$IS_APPROVED = 'Y')に一致しないときは、すべて終了イベント休暇却下に遷移します。

以上でフロー・ダイアグラムは完成です。変更の適用をクリックします。

フロー管理から休暇承認バージョン0を開きます。


作成したフロー・ダイアグラムが表示されることが確認できます。


以上で、休暇申請のフロー・モデルが作成できました。

続く

Flows for APEXによる休暇申請フローの作成(1) - Flows for APEXのインストール

 ドイツのMT GmBHが中心となって開発しているオープン・ソースのOracle APEXの拡張機能、Flows for APEXを使ってみます。BPMN 2.0で記述したビジネス・プロセスをOracle APEXで実行させるツールです。開発はGitHub上で行われています。

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


Flows for APEXのインストール



すでにFlows for APEXがインストールされていて、最新バージョンの23.1にアップグレードする場合はマイグレーションを実施します。マイグレーションを行うスクリプトはGitHubのリポジトリからダウンロードします。

これからFlows for APEXを新規インストールする手順を紹介します。

Flows for APEXのページよりDownloadを実行します。FlowsForAPEX_v23.1.zipというファイルがダウンロードされます。

ダウンロードしたZIPファイルを解凍します。解凍したディレクトリに含まれるApplications以下にflowsforapex_apex202.sqlというファイルがあります。これをAPEXアプリケーションとして、ワークスペースにインポートします。

% ls -l Applications 

total 71016

drwxr-xr-x@ 3 ynakakoshi  staff        96  4 28 15:15 Enable_Timers

drwxr-xr-x@ 3 ynakakoshi  staff        96  8 10 12:05 REST_Modules

-rw-r--r--@ 1 ynakakoshi  staff  31009731  8 10 12:14 flowsforapex_apex202.sql

-rw-r--r--@ 1 ynakakoshi  staff   5347202  8 10 12:15 flowsforapex_sample_app_apex202.sql

% 

フロー・モデルおよびダイアグラムの作成、編集、削除などを行なうアプリケーションになります。

今回の作業は、Always FreeのAutonomous Transaction Processingのインスタンス(Oracle APEX 23.1)で実施します。

アプリケーション・ビルダーからインポートを実行します。特別な作業はなく、通常のアプリケーションのインポート作業です。

ドラッグ・アンド・ドロップの領域にインポートするアプリケーションのファイルとして、flowsforapex_apex202.sqlを選択します。ファイル・タイプはデフォルトのアプリケーション、ページまたはコンポーネントのエクスポートファイルの文字セットUnicode(UTF-8)のまま変更しません。

へ進みます。


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


アプリケーションのインストール画面に移ります。次のアプリケーションとしてインストールの選択は、新規アプリケーションIDを自動割当てのまま変更せず、アプリケーションのインストールを実行します。


サポートするオブジェクトのインストールONになっていることを確認し、へ進みます。

Flows for APEXが扱うデータを保存する表は、サポートするオブジェクトとしてアプリケーションのインストールと同時に作成されます。


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


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


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


以上でFlows for APEXのインストールは完了です。

続く

カスケードLOVのソース定義について

 2つのページ・アイテムがあり、それぞれタイプがシャトルとなっています。このページ・アイテムには親子関係があり、親となるシャトルで選択した値に基づき、子のシャトルで選択できる値が決まります。

サンプル・データセットのEMP/DEPTをデータ・ソースとして使い、以下のようなページを作成します。



基本の実装



親のシャトルがP1_DEPTNOとして作成されています。表DEPTからDEPTNOを複数選択します。

LOVSQL問合せは以下になります。

select dname d, deptno r from dept


従業員を選択する子であるシャトルはP1_EMPNOとして作成されています。

LOVSQL問合せは以下になります。カスケードLOV親アイテムとしてP1_DEPTNOを指定します。親アイテムとして指定したアイテムは必ず送信されるため、送信されるアイテムに指定する必要はありません。

ページ・アイテムに複数の値が設定される場合、それぞれの値は':'(コロン)で区切られます。そのため、P1_DEPTNOの値をapex_string.splitを呼び出して分割しています。

ページ・アイテムP1_DEPTNOのシャトルで選択した部門の従業員に限り、P1_EMPNOのシャトルで選択できるようになります。


ここまでが基本の実装です。


SQLを記述できない場合



従業員の表がそれぞれ部門で分割されているケースを想定します。

create table emp_accounting as select * from emp where deptno = 10;
create table emp_research as select * from emp where deptno = 20;
create table emp_sales as select * from emp where deptno = 30;
create table emp_operations as select * from emp where deptno = 40;


部門ごとに4つの表が作られています。EMP_ACCOUNTINGEMP_RESEARCHEMP_SALESEMP_OPERATIONSです。親となるシャトルではこれらの表を選択し、子となるシャトルは選択された表から従業員を選択します。

親のシャトルのSQL問合せは以下に変わります。

select dname d, 'EMP_' || dname r from dept

ページ・アイテムP3_DEPTNOはコロンで区切られた表名を複数持ちます。


子のシャトルでは、LOVタイプSQL問合せを返すファンクション本体に変更し、SQL問合せを戻すPL/SQLファンクション本体として以下を記述します。ファンクションの評価時はページ・アイテムP3_DEPTNOはnullになります。評価に失敗するため、0行を返すダミーのSELECT文を戻しています。

カスケードLOVは基本と同じ設定になります。



動的にSELECT文を作成できない場合



動的にSQLを作る場合でも、最終的には実行可能なSELECT文が生成される必要があります。SELECT文を作るのが困難なケース(RESTサービスを呼び出すなど)では、パイプライン表関数を作成することで対応できる場合もあります。

今回の例を実装すると、以下のようになります。

作成したパイプライン表関数get_cascade_lov_sourceを使用したSQL問合せは以下になります。

select display_value, return_value from table(get_cascade_lov_source(:P2_DEPTNO))

パイプライン表関数による実装の場合、表示値と戻り値を返せばよいので実際のデータ・ソースが表である必要はありません。



カスケードLOVの親アイテムを指定できない場合



あまり無いとは思いますが、カスケードLOVの親アイテムを設定できない場合を考えてみます。

この場合、親となるページ・アイテムが変更されたときに、子となるページ・アイテムをリフレッシュする必要があります。


ページ・アイテムの変更イベントでページ・アイテムのリフレッシュを実行します。このTRUEアクションは、一般的なリフレッシュの設定です。


子アイテムのLOVSQL問合せ、または、ファンクション本体に親アイテムであるページ・アイテムがバインド変数として使用されている場合、カスケードLOVの親アイテムを指定せずに、送信するページ・アイテムを指定する方法はありません

このため、親となるページ・アイテムのセッション・ステートストレージセッションごと(永続)に切り替えます。


TRUEアクションを作成し、子であるページ・アイテムをリフレッシュする前に配置します。

アクションサーバー側のコードを実行を選択します。PL/SQLコードは不要なのでnull;とします。送信するアイテムとして親となるページ・アイテムを指定します。

セッション・ステートの定義はセッション(永続)になっているため、送信されたページ・アイテムの値はデータベースに保存されます。子アイテムのソースとなるコードが実行される際に、サーバーに保存されている値がバインド変数に割り当てられるため、親アイテムの値が反映された結果が得られます。


今回の記事は以上です。

検証に使用したアプリケーションのエクスポートを以下に置きました。
https://github.com/ujnak/apexapps/blob/master/exports/cascade-shuttle-lov-source.zip

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