前提と注意事項

この記事では以下を前提としています。

• Paperless ngx は Docker compose を使って構築、稼働させる前提です。
• Paperless ngx を動作させるのは Ubuntu22.04 上になります。

以降では、Paperless ngx を単に Paperless と表記します。 なお、この記事では Paperless ngx の公式ドキュメントである以下を参考にしています。

この記事のゴール

この記事では、Paperless に新しくファイルをアップロードしたり、Consume フォルダにファイルを追加したりした後に、Paperless によってファイルが処理されて登録されたことをトリガとして、追加したファイル情報を指定したテキストファイルに追記するスクリプトを実行できるようにします。

Paperless に追加したファイル情報をテキストファイルに追記するだけでは特に実用上大きな利便性はありませんが、指定したスクリプトファイルなら何でも実行できるため、Paperless をより有効活用するために大変便利です。

活用事例

本記事の内容を活用して以下のようなシステムの構築を行うことができました。

1. スマートフォンで撮影したレシートを OCR 処理した上で Paperless にアップロードする（別アプリ使用）
2. Paperless にレシート画像と情報が登録されると同時に、登録したレシート情報（OCR によって読み取った内容）を ChatGPT に送信する（OpenAI API を利用）
3. ChatGPT がレシートの内容から会計システムに保存したいデータ（レシートに含まれる金額や購入した製品名、購入日時、購入場所など）を抽出し、整形したデータを返信する
4. 返却された データをそのまま会計システムの API に送信して、会計システムにレシート情報を保存する

上記によって、スマートフォンでレシートを撮影するだけで、Paperless にレシート画像と情報が登録されて、さらに別の会計システムにもその情報が書き込まれるシステムになります。ただし、OCR 機能や ChatGPT による処理が１００％正確ではないため、多少の手直しは必要ですが、それでも大幅な効率化が図ることができました。

事前準備

Paperless を Docker Compose で動かすために、適当なディレクトリ~/paperless-ngxを作成し、そこに移動します。

$ mkdir ~/paperless-ngx
$ cd ~/paperless-ngx

その後、docker-compose.ymlを作成します。

$ vi docker-compose.yml

docker-compose.ymlの内容は次に記載します。

Paplerss の docker-compose.yml を修正する

Paperless においてファイルの追加時にスクリプトを実行するためには、Docker compose の設定を変更する必要があります。 具体的には、以下のようにPAPERLESS_POST_CONSUME_SCRIPTという項目を追記します。

version: '3.4'
services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    volumes:
      - ./redisdata:/data
 
  db:
    image: docker.io/library/postgres:15
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless
 
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - '8001:8000'
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
      - ./scripts:/usr/src/paperless/scripts
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_POST_CONSUME_SCRIPT: /usr/src/paperless/scripts/post-script.sh
 
volumes:
  data:
  media:
  pgdata:
  redisdata:

上記では、Paperless にファイルが追加、登録された後に/usr/src/paperless/scripts/post-script.shを実行するように設定しています。なお、/usr/src/paperless/scripts/post-script.shはコンテナ内のパスなので、これをホストマシン（Ubuntu 22.04）の./scriptsにバインドしています。すなわち、Ubuntu の~/paperless-ngx/scriptsに実行したいスクリプトファイルを作成します。

スクリプトを用意する

続いて Paperless へのファイル追加時に実行したいスクリプトファイルを保存するための適当なディレクトリを作成し、その中にpost-script.tsというスクリプトファイルを作成します。

$ mkdir ./scripts
$ cd ./scripts
$ vi post-script.sh

post-script.shの内容を以下のようにしました。以下のスクリプトは、公式ドキュメントにあるPost-consumption scriptのものを使っています。

#!/usr/bin/env bash
 
echo "
 
A document with an id of ${DOCUMENT_ID} was just consumed.  I know the
following additional information about it:
 
* Generated File Name: ${DOCUMENT_FILE_NAME}
* Archive Path: ${DOCUMENT_ARCHIVE_PATH}
* Source Path: ${DOCUMENT_SOURCE_PATH}
* Created: ${DOCUMENT_CREATED}
* Added: ${DOCUMENT_ADDED}
* Modified: ${DOCUMENT_MODIFIED}
* Thumbnail Path: ${DOCUMENT_THUMBNAIL_PATH}
* Download URL: ${DOCUMENT_DOWNLOAD_URL}
* Thumbnail URL: ${DOCUMENT_THUMBNAIL_URL}
* Correspondent: ${DOCUMENT_CORRESPONDENT}
* Tags: ${DOCUMENT_TAGS}
 
It was consumed with the passphrase ${PASSPHRASE}
 
" >> /usr/src/paperless/scripts/consumed_list.txt

上記は、/usr/src/paperless/scripts/consumed_list.txtというテキストファイル（Ubuntu 上では~/paperless-ngx/scripts/consumed_list.txt）に、追加されたファイルの情報を追記するスクリプトです。 なお、上記のスクリプトファイルに含まれているDOCUMENT_IDやDOCUMENT_FILE_NAMEなどの埋め込まれている変数は、Paperless が処理したファイルの情報です。

上記のスクリプトでは実用性はありませんが、例えばDOCUMENT_IDを使って Paperless の REST API に GET リクエストを送信して処理されたファイルの詳細な情報を取得し、その情報を別のシステムの API を通して書き込む ということもできます。

上記のスクリプトファイルを実行できるよう、実行権限を付与します。

$ chmod +x ./post-script.sh

Paperless を起動する

あとは以下で Paperless を起動します。必要に応じてsudoを使うなどしてください。

$ docker compose up -d

あとは実際に Paperless の Web ダッシュボードから新しいファイルをアップロードしたり、Consume フォルダにファイルを追加したりしてconsumed_list.txtが更新されるか確認してみてください。

ファイルの登録前にスクリプトを実行したい場合

以上で Paperless にファイルを追加して、Paperless にファイルが登録された後にスクリプトを実行できる環境を構築できました。 逆に Paperless にファイルが登録される前にスクリプトを実行することもできます。この場合は、PAPERLESS_PRE_CONSUME_SCRIPTを使用します。 該当部分を抜粋すると、docker-compose.ymlは以下のようになります。

environment:
  PAPERLESS_REDIS: redis://broker:6379
  PAPERLESS_DBHOST: db
  PAPERLESS_POST_CONSUME_SCRIPT: /usr/src/paperless/scripts/post-script.sh
  PAPERLESS_PRE_CONSUME_SCRIPT: /usr/src/paperless/scripts/pre-script.sh

上記のようにすると、Paplerss ngx にファイルが追加された時に、Paperless にファイルが登録される前に/usr/src/paperless/scripts/pre-script.shを実行することができます。

まとめ

Paperless ngx で新しいファイルを追加した時に指定したスクリプトを実行する方法について解説しまました。Paperless は大変便利なツールですが、本記事で紹介したようにファイルの追加前後で任意の処理を実行することでさらに便利になります。