Introduction

Pegaが外部システムから情報を取り込む方式の一つとして、ファイル形式での連携はよく使われる。
ここでは、ファイルをサーバに格納する→Pegaで取り込む、開発でよくある定番の処理について説明する。

Scenario

外部システムから定期的に決まった場所にCSVファイルを連携してくる
- CSVファイルのサンプルは以下通り。
- 決まった場所とは
  Pegaがアクセス・書き込み権限を持つ、Pegaがdeployされているサーバ上に存在する場所。
  PEバージョンでの例：C:\PRPCPersonalEdition\tomcat\webapps\prweb\batch\POCApp231012\InputFiles
Pega側でファイルを読み込み、行ごと読み込んだデータをログに出力する
処理済みのファイルはバックアップフォルダーに移動する

上記シナリオ実現するに当たって、PegaではFile Listenerを含めて以下一連のruleを使用している。
ここでは処理のトリガーとなるFile Listenerのみを紹介する。
（ほかのRule typeは別記事で掲載する予定）

File Listerner - 特定の場所を監視し、対象ファイルを検知できたら処理を呼び出す。
Service File - ファイルに対しする処理を定義するRule、File listenerから参照される
Parse Delimited - 読み込んだcsvデータの項目名と、Pega内部のProperty名とのマッピング定義。Service Fileから参照される。

File listerner作成

Records→Integration-Resources→File Listener→Create
名前を入力し、作成ボタンを押す

Configuration points

作成できたFile listernerのrule formは以下通り。
タブごとに設定箇所を解説していきます。

1. 一時的に実行不可にしたい場合

Block startup - チェック入れた場合実行不可となる
実行不可にしたい場合以外、常にチャックを外す。

2. 処理を実行するNodeを指定できるか

Startup option -file listenerを実行するnodeを指定する

a)Run on all nodes – cluster上にある全nodeで実行可能
b)Node based startup – リストに追加したnodeでしか実行できない（node id指定）
c)Host based startup – リストに追加したnodeでしか実行できない（hostname指定）
指定したhostnameを持つのnode群から、指定した数までnodeをランダムに選んで処理を実行する
d)NodeClassification based startup – 指定したnode typeでのみ実行可能

このシナリオでは、Personal editionで実現しているため、Nodeは一個しかないので、a)Run on all nodes にする。

3. 監視場所および対象ファイル名、拡張子を設定する

Source location - the file specification for the file listener to look for input files.

P.S.ここではハードコーディングで設定していますが、DataPageなどを使って動的に読み込むのがおすすめ。
DataPageの使用例：ApplicationSettingsから値を取得する
D_pxGetApplicationSettingValue[OwningRuleset:"PegaUnitTests:01-01-01",Purpose:"URLSetting"].pySettingValue
Source name mask - the filter for selecting files to process from the source location directory.
ファイル名が特定のパターンに満たすもののみが、処理対象として読み込まれます。
Disable case sensitivity - チェックを入れた場合、ファイル名にある大文字小文字が区別されなくなる
ここでは区別をつけたいので、チェックを入れない。

P.S.任意のファイルを対象とする場合、*.*でsource name maskを指定する

ここではファイル名がinputから始まり、且つ拡張子がcsvのファイルを処理対象とする。

4. パラレル処理で性能向上を図る

Concurrent threads - the number of threads on each server node that the listener requestor creates when it starts.
おすすめ指定範囲：1~5
複数のファイルを処理対象とする場合、1nodeで複数のthreadを並行実行することで、処理スピードを上げれる。
ただ、1個のファイルを処理する場合特にメリットなし。

このシナリオでは、対象ファイルは一個しかないので、1に指定する。

5. 対象ファイルを検知できたタイミングで、実行したい処理を設定する

Service package - 実行したい処理に該当するルール名の一部
Service class - 実行したい処理に該当するルール名の一部
Service method - 実行したい処理に該当するルール名の一部

上記3項目の組み合わせで実行するService Fileルールを指定する
Service Fileルールについては別記事で解説する予定。

6. 監視場所へのアクセステスト

上記ボタンを押して、file listenerを実行するnodeから監視場所へアクセスできるかを確認できる。
問題なくアクセスできた場合、以下画面が表示される

7. Service Package呼び出す際、認証情報が要求される場合がある。

その際使用する情報は以下項目を指定して設定する

Requestor login - If the file service requires requestors to be authenticated, configure the requestor login information
- Requestor user ID
- Password

Service Packageについては後日別記事で解説する

8. ファイル検知の間隔を以下項目で秒数で設定可能

Polling interval (seconds) - the number of seconds that the listener waits before it checks for newly arrived files.

ここはデフォルトの60sで設定する

9. すでに処理済みファイルと同じ名前のファイルが格納されたら、処理対象外にするか設定可能

Ignore duplicate file names - To prevent processing of a file that has the same name as a previously processed file
チェックを入れた場合、ファイル名の最後に.dupをつけたうえ、監視場所/work/にファイルが移動される

ここは同じ名前のファイルでも処理対象としたいので、チェックを入れない。

10. 複数のnodeでfile listenerを実行する場合、各nodeで同じfile listenerのinstanceが作成されて実行される

1ファイルを1nodeで処理するように、先にファイル処理を始めたfile listenerが作成した一時的ファイルにロックをかける必要がある。

Lock listener's temporary file - To avoid name collisions when multiple copies of the listener are running

このシナリオでは1nodeのみですので、チェックを外す。

11. 空ファイルを処理対象外にするか

Process empty files - To process files without content

空ファイルも検知対象にしたいので、チェックを入れる。

P.S.file listenerを修正後、以下操作で最新の状態を読み込む必要がある
Admin Studio→Resources→Listeners→対象Listenerを選択→Restart

P.S.file listenerをtraceする方法：
Admin Studio→Resources→Listeners→対象Listenerを選択→Actions→Trace service in cluster

12. 処理ログの出力仕様について

出力イメージ：file監視場所/reportにXMLファイル形式で出力する

処理ログの出力仕様についてどこまで設定できるか

Source page name - ログ内容が格納されているpgae名（file listenerの実行をtraceする際、該当pageが見つからなかったのでイマイチ使い方がわからん。。）
Source property - Source page name配下のどのpropertyをログ内容として出力する
- Source pageのclassがLog-Service-Fileのため、その配下にある任意のpropertyを設定できる（例えば：pyFileName）
- Default値の$XMLは、Source page全体の内容をXML形式で出力対象とする
Target file extension - 出力するログファイルの拡張子
Generat report file - チェック入れた場合のみ、ログが出力される
Persist Log-Service-File instance - チェック入れた場合のみ、ログをinstanceとして以下イメージでPegaのDBに永久保存する

13. 処理済みのファイルを削除するか

File operation - Keepの場合のみ、処理済みのファイルをファイル監視場所/work_<listenername>_completedに保存する

処理終了後行われる後処理を設定する

Activity class - 後処理ActivityのClass
Activity name - 後処理Activityのrule name

エラーハンドリングについて

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/964036cb-310e-fd8a-d1e5-cc698b88c630.png)

Attempt recovery - チェック入れた場合のみ、処理失敗時にretry処理が行われる
Max recovery attempts - retry 回数

File operation - 処理失敗時に、監視対象ファイルを削除するか、名前を変えて残すか設定できる
File extension - File operationがRenameに指定された場合、監視対象ファイルにつける拡張子を指定する

Implementaion details

最後に作成したfile listener全体の設定とその実行結果をここに貼り付けます。

Preparation

File Listener設定
監視場所
サンプルファイル

Operation

上記サンプルファイルを監視場所に格納して、60s以内に処理が始まる
しばらく経って、ファイルが消えてフォルダーが二つできている。
/report配下にログが吐かれる
/work_<listenername>/completed配下に、処理済みのファイルが格納される
Pegaログからも、csvファイルの内容が出力されているのを確認できる

References