コンテンツにスキップ
「プリザンター入門」発売中!

$ps.file.export

概要

サーバスクリプトで$ps.fileを使用してエクスポートをする際に使用します。

前提条件

  1. Script.jsonのDisableServerScriptFileを false に設定することが必要です。
  2. テーブルの「エクスポート権限」が必要です。

構文

$ps.file.export(section, path, siteId, json);

パラメータ

パラメータ 型 必須 説明
section string ○ セクション名。セクションについては$ps.fileの「セクションについて」を参照ください。
path string ○ ファイル名。ディレクトリの区切り文字はWindow、Linux共に「/」を利用する。
siteId string ○ サイトID
json string ○ エクスポート用パラメータ

戻り値

成功した場合にtrueを返します。失敗した場合はfalseを返します。

例外

C#内で例外が発生した場合はサーバスクリプト内に例外クラス名とエラーメッセージをErrorオブジェクトに入れて例外を発生させます。

使用例

以下の例では、Webサーバ内のcsvファイルのエクスポートを行い、結果をログに出力します。

(a) 標準のエクスポート設定でテーブルをエクスポートする。

JavaScript
const siteId = 100;
const param = {
};
const result = $ps.file.export('01_develop', 'parts/01_parts.csv', siteId, $ps.JSON.stringify(param));
context.Log(result);

(b) 文字コード:Shift-JIS の例

JavaScript
const siteId = 100;
const param = {
    Encoding = "Shift-JIS"
};
const result = $ps.file.export('01_develop', 'parts/01_parts.csv', siteId, $ps.JSON.stringify(param));
context.Log(result);

(c) Pleasanterで作成済みのエクスポート設定を使用してテーブルをエクスポートする

JavaScript
const siteId = 100;
const param = {
    ExportId: 1
};
const result = $ps.file.export('01_develop', 'parts/01_parts.csv', siteId, $ps.JSON.stringify(param));
context.Log(result);

(e) 直接記述してテーブルをエクスポートする

JavaScript
const siteId = 100;
const param = {
    Export: {
        Columns: [
            {
                ColumnName: 'ClassA'
            },
            {
                ColumnName: 'UpdatedTime'
            }
        ],
        Header: false,
        Type: 'csv'
    }
};
const result = $ps.file.export('01_develop', 'parts/01_parts.csv', siteId, $ps.JSON.stringify(param));
context.Log(result);

サンプルコード

コード内の【 ... 】 は適宜修正してください。
1. 任意のフォルダにテーブルのデータをエクスポートする

任意のフォルダにテーブルのデータをエクスポートするサンプルコードです。

実務での使いどころ

会計システムや基幹システムへ、プリザンターのデータを決まったフォルダ経由で定期的に渡したいときに使えます。前回出力したファイルをバックアップのフォルダへ移してから出力するので、受け取る側が古いファイルを取り込む誤りを防げ、過去に渡したファイルも後から確かめられます。

以下処理イメージです。
前回エクスポートしたCSVファイルをbackup/sendへ移動し、エクスポートしたCSVファイルをsendフォルダへ格納する処理イメージ
①sendフォルダに格納されている前回エクスポートしたCSVファイルをbackup/sendへ移動
②エクスポートしたCSVファイルをsendフォルダへ格納

コードの途中で return を使っているため、サーバスクリプトの「関数化」を有効にしてください。

JavaScript
// 各種設定
const SECTION = 'files';
const SEND = 'send';
const BACKUP_SEND = 'backup/send';
const SITE_NAME = '【サイト名】';
const FILE_DATE_FORMAT = 'utilities';
// 処理日時の文字列取得
function getDateTimeString() {
    return new Date()
        .toLocaleString('ja-JP', {
            year: 'numeric',
            month: '2-digit',
            day: '2-digit',
            hour: '2-digit',
            minute: '2-digit',
            second: '2-digit',
            hour12: false, // 24時間表示
        })
        .replaceAll('/', '')
        .replaceAll(':', '')
        .replaceAll(' ', '');
}
// サイト情報取得
const site = items.GetClosestSite(SITE_NAME);
if (!site) {
    logs.LogException(`サイト:${SITE_NAME}が見つかりません。`);
    return false;
}
const siteId = site.SiteId;
// 送信フォルダにあるファイルをバックアップフォルダに移動
const lists = $ps.file.getFileList(SECTION, SEND);
if (lists.length > 0) {
    for (const element of lists) {
        const moveResult = $ps.file.moveFile(
            SECTION,
            `${SEND}/${element}`,
            `${BACKUP_SEND}/${element}`,
        );
        if (!moveResult) {
            logs.LogException(`ファイル移動失敗 ファイル名:${element}`);
            return false;
        } else {
            logs.LogInfo(`ファイル移動成功 ファイル名:${element}`);
        }
    }
}
// ファイルエクスポート:エクスポート定義のID:1を使用。対象レコードは「対象月が今年」のレコード
const param = {
    ExportId: 1,
    View: {
        ColumnFilterHash: {
            DateA: '["ThisYear"]',
        },
    },
};
const path = `${SEND}/${FILE_DATE_FORMAT}${getDateTimeString()}.csv`;
const exportResult = $ps.file.export(
    SECTION,
    path,
    siteId,
    $ps.JSON.stringify(param),
);
if (!exportResult) {
    logs.LogException(`エクスポートに失敗しました。 ファイル名:${path}`);
    return false;
} else {
    logs.LogInfo(`エクスポート成功 ファイル名:${path}`);
}
2. 毎月、テーブルの控えを月のフォルダに出し、保存する月数より古い月のフォルダを消す

バックグラウンドサーバスクリプトで毎月、決めておいたテーブルを$ps.file.exportでCSVに出し、セクションexportsのmonthly/YYYY-MM(実行した日の年月)のフォルダに保存します。今月の控えがすべてそろったら、monthlyの下の月のフォルダのうち、保存する月数より古いものを$ps.file.removeDirectoryで消します。同じ月にもう一度実行しても、出力済みのファイルは出し直しません。

実務での使いどころ

資産台帳・在庫・顧客台帳・契約一覧などを、月の初めの時点のCSVとして残したいときに使えます。監査や月次の締めで、その月の初めの内容をファイルで確かめられます。標準のエクスポートは一覧画面で人が実行する操作で、決まった日にサーバのフォルダへ保存する機能はありません。毎月エクスポートしてサーバに置く手間・置き忘れと、古い控えがたまり続けることを防げます。

事前準備

1:Script.jsonで、DisableServerScriptFileをfalse、ServerScriptFilePathに基準ディレクトリ、BackgroundServerScriptをtrueにし、プリザンターを再起動してください。バックグラウンドサーバスクリプトは特権ユーザのみ設定できます。

2:基準ディレクトリの下に、セクションexportsと、その下のmonthlyフォルダを作っておきます。

3:サンプルコードのTARGETSに、控えを出すテーブルのサイトIDとファイル名を書きます。決まった項目で出すときは、テーブルの管理の「エクスポート」タブで書式を作り、その書式のIDをExportIdに書きます。paramを空にすると、標準のエクスポート設定で出します。

4:バックグラウンドサーバスクリプトを登録します。

4-1:「テナントの管理 > サーバスクリプト」タブで「新規作成」を選択する。
 4-2:実行ユーザ: 控えを出すテーブルのエクスポート権限を持つユーザ
 4-3:タイトル: 任意の名前(例:exportMonthlyAndRemoveOld)
 4-4:サーバスクリプト: 下記サンプルコードを貼り付け
 4-5:スケジュール: 「毎月」で、1日と実行する時刻(例:9:00)を設定
 4-6:「追加」をクリックし、画面下部の「更新」をクリックする

5:登録したスクリプトを開き、「今すぐ実行」で動かします。DRY_RUNがtrueのあいだはフォルダを消さず、消す予定のフォルダをシステムログに出します。今月のフォルダにCSVが出たこと、消す予定のフォルダを確かめてからDRY_RUNをfalseにしてください。

JavaScript
// 控えを出すセクションと、月のフォルダを置くフォルダ(どちらも事前に作っておく)
const SECTION = 'exports';
const BASE_DIR = 'monthly';
// 残す月数(今月を含む)。12 なら、今月から 12 か月以上前の月のフォルダを消す
const KEEP_MONTHS = 12;
// true のあいだはフォルダを消さず、消す予定のフォルダをログに出すのみ
const DRY_RUN = true;
// 控えを出すテーブル。param が空なら標準のエクスポート設定、ExportId でエクスポートの書式を指定できる
const TARGETS = [
    { siteId: 【資産台帳のサイトID】, file: 'assets.csv', param: {} },
    { siteId: 【顧客台帳のサイトID】, file: 'customers.csv', param: { ExportId: 【エクスポート設定のID】 } },
];

// 月を「年×12+月」の数にする(YYYY-MM の形でなければ null)
function monthNumber(name) {
    const m = /^(\d{4})-(\d{2})$/.exec(name);
    return m ? Number(m[1]) * 12 + Number(m[2]) : null;
}

// 今月のフォルダが無ければ作る
function ensureMonthDir(month) {
    if (Array.from($ps.file.getDirectoryList(SECTION, BASE_DIR)).includes(month)) {
        return true;
    }
    try {
        return $ps.file.createDirectory(SECTION, `${BASE_DIR}/${month}`);
    } catch (e) {
        logs.LogUserError(`フォルダを作成できませんでした:${BASE_DIR}/${month} ${e}`, 'exportMonthlyAndRemoveOld');
        return false;
    }
}

// まだ出していないテーブルの控えを出す
function exportTables(month, count) {
    const done = Array.from($ps.file.getFileList(SECTION, `${BASE_DIR}/${month}`));
    for (const target of TARGETS) {
        if (done.includes(target.file)) {
            count.skipped++;  // 出力済みのものは出し直さない
            continue;
        }
        let result = false;
        try {
            result = $ps.file.export(SECTION, `${BASE_DIR}/${month}/${target.file}`, target.siteId, $ps.JSON.stringify(target.param));
        } catch (e) {
            logs.LogUserError(`エクスポートで例外が発生しました:サイトID ${target.siteId} ${e}`, 'exportMonthlyAndRemoveOld');
        }
        if (result) {
            count.exported++;
        } else {
            count.failed++;
            logs.LogUserError(`エクスポートできませんでした:サイトID ${target.siteId} ${target.file}`, 'exportMonthlyAndRemoveOld');
        }
    }
}

// 保存する月数より古い月のフォルダを消す
function removeOldMonths(current, count) {
    const olds = Array.from($ps.file.getDirectoryList(SECTION, BASE_DIR))
        .filter((name) => monthNumber(name) !== null && current - monthNumber(name) >= KEEP_MONTHS);
    count.targets = olds.length;
    logs.LogInfo(`[exportMonthlyAndRemoveOld] 削除対象:${olds.join(', ') || 'なし'} DRY_RUN=${DRY_RUN}`, 'main');
    if (DRY_RUN) {
        return;
    }
    for (const name of olds) {
        let result = false;
        try {
            result = $ps.file.removeDirectory(SECTION, `${BASE_DIR}/${name}`);
        } catch (e) {
            logs.LogUserError(`フォルダの削除で例外が発生しました:${BASE_DIR}/${name} ${e}`, 'exportMonthlyAndRemoveOld');
        }
        if (result) {
            count.removed++;
        } else {
            logs.LogUserError(`フォルダを削除できませんでした:${BASE_DIR}/${name}`, 'exportMonthlyAndRemoveOld');
        }
    }
}

// 毎月、テーブルの控えを月のフォルダに出し、保存する月数より古い月のフォルダを消す
// (バックグラウンドサーバスクリプトで毎月実行する)
function exportMonthlyAndRemoveOld() {
    const now = new Date();
    const month = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
    const count = { exported: 0, skipped: 0, failed: 0, targets: 0, removed: 0 };
    if (!ensureMonthDir(month)) {
        logs.LogUserError(`今月のフォルダが無いため、処理を止めました:${BASE_DIR}/${month}`, 'exportMonthlyAndRemoveOld');
        return;
    }
    exportTables(month, count);
    // 今月の控えがすべてそろったときのみ、古い月を消す
    if (count.failed === 0) {
        removeOldMonths(monthNumber(month), count);
    }
    logs.LogInfo(
        `[exportMonthlyAndRemoveOld] 月=${month} 出力${count.exported}件 出力済み${count.skipped}件 失敗${count.failed}件 削除対象${count.targets}件 削除${count.removed}件`,
        'main',
    );
}

exportMonthlyAndRemoveOld();

注記

  • 実行した日の年月のフォルダに出します。スケジュールの時刻は、日付が変わる0時の前後を避けてください。
  • 消すのは、名前がYYYY-MMの形のフォルダのみです。ほかの名前のフォルダには触れません。KEEP_MONTHSが12のとき、今月から12か月以上前の月のフォルダを消します。
  • $ps.file.removeDirectoryは、フォルダの中のサブディレクトリやファイルもすべて削除します。
  • 1つでもエクスポートに失敗した月は、古い月のフォルダを消しません。失敗はシステムログに出します。
  • 出力済みのファイルは出し直しません。出し直すときは、今月のフォルダのファイルを消してから実行してください。
  • サイトIDは、$ps.file.exportの使用例のとおり数値で書きます。
  • ファイル名に使える文字は、$ps.fileの制限事項を確かめてください。件数の多いテーブルで処理タイムアウト時間を超えるときは、Script.jsonの「ServerScriptTimeOut」で調整します。

対応バージョン

対応バージョン 内容
1.4.13.0 以降 機能追加

関連情報