★★:まあまあ

本記事はSPA・invoiceAgentブランド統合に伴い、名称をinvoiceAgent 文書管理/AI-OCRに変更しました。


前回の記事「invoiceAgentのWeb APIを使ってみる2 ファイルの保存/アーカイブ」ではファイルのアーカイブ処理についてご説明しました。
今回はアーカイブ後に任意の値で検索できるよう、カスタムプロパティをセットした上でアーカイブ処理を行う方法についてご説明します。

実装は前回のソースコードに追加する形で行います。

言語はJavaを前提にしておりますが、他の言語でも仕組みや考え方は同じです。
以下の解説を一通り実装したサンプルを本記事の末尾のリンクよりダウンロードいただけます。

カスタムプロパティとは?

カスタムプロパティは、invoiceAgentにアーカイブされたすべての文書(ファイル、リンク、ページリンク、マルチリンク)やフォルダーを対象に、ユーザーが独自に追加できる属性です。文書やフォルダーごとに値を設定することができます。
カスタムプロパティを設定することで「文書やフォルダーのプロパティの1つとして表示する」「検索項目として利用する」「検索結果等の属性の一つとしてCSVでダウンロードする」といった用途があります。

<カスタムプロパティの表示イメージ>

カスタムプロパティの表示イメージ

詳細は以下マニュアルをご確認ください。

SPA製品ガイド > SPAを知る > SPAの主な機能 > カスタムプロパティ

一例ですが業務を想定するとカスタムプロパティは以下のような利用用途があります。


例1.伝票をスキャンしてinvoiceAgentへ保存、伝票番号をカスタムプロパティへセットし検索可能にする。

例2.経費精算システムと連動して請求書や領収書をinvoiceAgentへ保存。承認Noや精算番号をカスタムプロパティへセットし検索可能にする。

例3.電子帳簿保存法の電子取引要件を前提として、スキャンした文書をinvoiceAgentへ保存。取引年月日、取引金額、取引先名称をカスタムプロパティへセットし検索可能にする。

<例3のイメージ>

文書と他システムを連携するためのキー項目を保存したり、必要な検索要件を満たすための値をセットすることで様々な業務要件に対応できますね。

利用API archives_v3

利用APIは前回同様にarchives_v3ですが、カスタムプロパティをセットするためのパラメータ「customProperties」を追加します。

※今回はクラウド/オンプレどちらでも利用できるVer. 3の利用としましたが、機能強化に伴い新たなバージョンのAPIが追加されることがあります。実装時には最新バージョンのAPIを確認してください。

customPropertiesはjson形式で送信する必用があるため、まずはその書式を確認します。
詳細は以下マニュアルをご確認ください。

参考(マニュアル):SPA Web APIリファレンス > カスタムプロパティ操作 > カスタムプロパティ一括更新用ファイルの書式

送信するリクエストのイメージとしは以下のようなパート、JSON形式になります。

Content-Disposition: form-data; name="customProperties"
Content-Type: application/json; charset=UTF-8

{
    "customProperties": {
    "50": "1000",
    "51": "20220114",
    "52": "ウイングアーク1st"
    }
}


customPropertiesの値はカスタムプロパティID:値のようにセットします。

{
    "customProperties": {
    カスタムプロパティID:値,
    カスタムプロパティID:値,
    カスタムプロパティID:値
    }
}


カスタムプロパティIDの値はサーバ環境の設定>運用管理>カスタムプロパティ設定の画面で確認することができます。


JSONパラメータの送信メソッドの定義

カスタムプロパティのパートをPOSTするメソッドを定義します。

/**
* カスタムプロパティ書き込み処理 (取引金額、取引日付、取引先)
*
* @param dos DataOutputStream
* @param boundary boundary文字列
* @param amount 取引金額
* @param date 取引日付 yyyyMMdd
* @param customer 取引先
* @throws IOException 書き込み処理に失敗した場合
*/
private static void postcustomProperties(DataOutputStream dos, String boundary, int amount , String date, String customer)
throws IOException {

    dos.writeBytes("--" + boundary + CRLF);
    dos.writeBytes("Content-Disposition: form-data; name=\"" + "customProperties" + "\"" + CRLF);
    dos.writeBytes("Content-Type: application/json; charset=UTF-8" + CRLF);
    dos.writeBytes(CRLF);
    dos.writeBytes("{");
    dos.writeBytes(" \"customProperties\": {");

    //SPA_amount 取引金額
    dos.writeBytes(" \"50\": \"" + amount + "\",");
    //SPA_date 取引日付
    dos.writeBytes(" \"51\": \"" + date + "\",");
    //SPA_customer 取引先
    dos.writeBytes(" \"52\": \"");
    dos.write(customer.getBytes(StandardCharsets.UTF_8));
    dos.writeBytes("\"");

    dos.writeBytes(" }");
    dos.writeBytes("}");
    dos.writeBytes(CRLF);
}

POST処理

赤字のカスタムプロパティセット部分を追加します。

// マルチパートメッセージの作成
String boundary = "----SpaFormBoundary" + Long.toString(System.currentTimeMillis());
conn.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);

try (DataOutputStream dos = new DataOutputStream(new BufferedOutputStream(conn.getOutputStream()))) {
//path 保存先パス指定
postParam(dos, boundary, "path", path);
//name ファイル名指定
postParam(dos, boundary, "name", name);
//カスタムプロパティセット
postcustomProperties(dos, boundary, 1000, "20220114", "ウイングアーク1st株式会社");
//file ファイルデータそのもの送信
postFile(dos, boundary, "file", file.getName(), file);
dos.writeBytes("--" + boundary + "--" + CRLF);
}

実行

mainメソッドを呼び出して、実行してみます。
コンソールにはこんな感じの内容が表示されます。

ログイン成功
アーカイブ処理開始
送信完了
アーカイブ成功
ログアウト成功


invoiceAgentへアクセスしアーカイブされたファイルのカスタムプロパティを確認すると以下のようにセットされていることが確認できますね。

カスタムプロパティがセットされている最後に

今回はWeb APIを利用しアーカイブする際にカスタムプロパティをセットしてみました。
単にファイルを保管するだけでなく、活用できる状態で保管するのにカスタムプロパティをセットしておくことは大変有用ではないかと思います。
ぜひご活用いただければと思います。


今回ご説明した一連の処理を実行できるサンプルのソースファイルを以下のリンクからダウンロードいただけますので参考にしてみてくださいね。

WebApiSampleArchives2.javaをダウンロード


※右クリックして「名前を付けてリンク先を保存」等の機能でローカルに保存した上でご確認ください。ファイルの文字コードはUTF-8です。そのまま開くと文字化けして表示される場合があります。
※オンプレ版invoiceAgentで利用する場合はXSRF-TOKENの処理はコメントアウトしてご利用ください。
※本記事の情報は、2022年01月14日現在のものです。(SPA V10.6.1 / SPA Cloud Ver.10.6.1.1017)