【ファイル処理】File listenerを作成する流れ

## Introduction

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

## Scenario

1. 外部システムから定期的に決まった場所にCSVファイルを連携してくる  
	- CSVファイルのサンプルは以下通り。 
	![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/41bf1bdd-950f-9421-27d3-bfcd7c71b450.png)
 
	- 決まった場所とは  
	Pegaがアクセス・書き込み権限を持つ、Pegaがdeployされているサーバ上に存在する場所。  
	PEバージョンでの例：`C:\PRPCPersonalEdition\tomcat\webapps\prweb\batch\POCApp231012\InputFiles`

	
	
2. Pega側でファイルを読み込み、行ごと読み込んだデータをログに出力する  

3. 処理済みのファイルはバックアップフォルダーに移動する  

上記シナリオ実現するに当たって、PegaではFile Listenerを含めて以下一連のruleを使用している。  
ここでは処理のトリガーとなるFile Listenerのみを紹介する。  
（ほかのRule typeは別記事で掲載する予定）   
- File Listerner - 特定の場所を監視し、対象ファイルを検知できたら処理を呼び出す。  
- Service File - ファイルに対しする処理を定義するRule、File listenerから参照される  
- Parse Delimited - 読み込んだcsvデータの項	目名と、Pega内部のProperty名とのマッピング定義。Service Fileから参照される。





## File listerner作成

1. Records→Integration-Resources→File Listener→Create
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/f17cbebe-716e-7b71-bdbc-53ae591bb152.png)

2. 名前を入力し、作成ボタンを押す
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/7f321d72-d946-aadb-3f7d-95ab70ba061c.png)



## Configuration points

作成できたFile listernerのrule formは以下通り。  
タブごとに設定箇所を解説していきます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/cdc03662-f142-5b83-ce2e-f7b252296d7a.png)

#### 1. 一時的に実行不可にしたい場合
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/3eaf4454-1129-296a-b84d-cb9f6c24732c.png)

- Block startup - チェック入れた場合実行不可となる  
実行不可にしたい場合以外、常にチャックを外す。  
	
#### 2. 処理を実行するNodeを指定できるか

Startup option -file listenerを実行するnodeを指定する
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/1f3152bd-276c-f2e6-18f0-ba9ed8a5527b.png)

- a)Run on all nodes – cluster上にある全nodeで実行可能
	
- b)Node based startup – リストに追加したnodeでしか実行できない（node id指定）
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/961d755c-4005-f916-d1ce-83e4a411bca2.png)

- c)Host based startup – リストに追加したnodeでしか実行できない（hostname指定）  
指定したhostnameを持つのnode群から、指定した数までnodeをランダムに選んで処理を実行する
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/7f02401d-0242-a696-21d8-f5c7cdcacb62.png)

	
- d)NodeClassification based startup – 指定したnode typeでのみ実行可能
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/23d88431-9376-2beb-06d1-50623e5b9435.png)

このシナリオでは、Personal editionで実現しているため、Nodeは一個しかないので、a)Run on all nodes にする。
	
#### 3. 監視場所および対象ファイル名、拡張子を設定する

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/dbd4859e-1d5a-0807-2c58-5b6e3593144d.png)

- 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. パラレル処理で性能向上を図る

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/b57999f2-3586-a878-260f-795fc4f540a2.png)

- 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. 対象ファイルを検知できたタイミングで、実行したい処理を設定する

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/00dd2c9b-7a00-642a-5e23-9deed4514c1d.png)

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

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

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

上記3項目の組み合わせで実行するService Fileルールを指定する  
Service Fileルールについては別記事で解説する予定。
	
#### 6. 監視場所へのアクセステスト

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/4b939141-5ca8-e659-85b2-475e712efc87.png)

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/26cc4526-f6ee-85bc-b73b-51ea92078a01.png)


#### 7. Service Package呼び出す際、認証情報が要求される場合がある。  
その際使用する情報は以下項目を指定して設定する

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/5d0b4e95-8690-5095-fd8c-8ea3b9664739.png)


- Requestor login - If the file service requires requestors to be authenticated, configure the requestor login information
	- Requestor user ID
	- Password
		
Service Packageについては後日別記事で解説する


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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/13825ba6-e023-5262-ba63-e21b9871229d.png)

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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/1f8039fd-31cc-3754-3376-b7ba0b28429c.png)

- 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が作成した一時的ファイルにロックをかける必要がある。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/1d9873a2-7055-45ec-67a3-0567a77bb0d7.png)

- Lock listener's temporary file - To avoid name collisions when multiple copies of the listener are running
	
このシナリオでは1nodeのみですので、チェックを外す。
	
#### 11. 空ファイルを処理対象外にするか

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/d4504177-b346-859d-9dfa-d579f5e5a02f.png)

- Process empty files - To process files without content
	
空ファイルも検知対象にしたいので、チェックを入れる。

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/ef03bd2b-d854-a229-73ce-b015843f44eb.png)

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/e8af77ed-241a-04dc-4c03-761f4254e3b7.png)


#### 12. 処理ログの出力仕様について  
出力イメージ：`file監視場所/report`にXMLファイル形式で出力する

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/660ae72b-31fc-8d46-bbef-b650c97f972f.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/96c4fbef-713a-159f-4386-fc818335b72f.png)

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/738b4711-f5a3-114f-33bf-a9aa96022c74.png)

- 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に永久保存する

    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/dff0dfa6-803a-3892-0dde-1cdd39caca81.png)

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/f9b95b25-8d81-e433-52c5-0048cf3dd45c.png)

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/ce615a38-465f-6a58-1e30-c36d84602bb5.png)

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/aeb1bb6b-7c50-f020-ccf6-f3a1f56b47ad.png)

- 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 回数

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/ca0e97d9-4496-7c01-4cef-55ce7d0a5883.png)

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


## Implementaion details

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

### Preparation
- File Listener設定
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/31bf9dd3-e5de-ddc6-35e9-00c1bdc3ae9d.png)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/5114f35e-77bf-e78e-b0f7-47689592711e.png)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/1c6aa0a1-090f-6b3d-15a8-95ea6210a92a.png)

- 監視場所
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/8334d119-839e-661d-cd41-d880d2e41b1a.png)

- サンプルファイル
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/1fde6707-36ba-e59b-3b01-a38a2062a35d.png)
### Operation

1. 上記サンプルファイルを監視場所に格納して、60s以内に処理が始まる
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/3cfca61e-94be-4c87-ece2-203bccd1d0f8.png)

2. しばらく経って、ファイルが消えてフォルダーが二つできている。
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/896ca1f9-5a69-7a90-bbd9-dfb917c3442b.png)

3. `/report`配下にログが吐かれる
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/9fbfd27e-38bc-5e1d-31f1-7864316cfa16.png)

4. `/work_<listenername>/completed`配下に、処理済みのファイルが格納される
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/ec88f9a5-1a36-0f51-dec7-752992460187.png)

5. Pegaログからも、csvファイルの内容が出力されているのを確認できる
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3676604/b5457b63-8e6b-11d7-e6b4-6da7a8025cc9.png)


## References