📝
コラボフロー API を使って添付ファイル付きの申請書を送信する

Shota
2024/12/09に公開
API
コラボフロー
tech
 はじめに本記事では、コラボフローAPI と Node.js を使って、コラボフローの外から添付ファイル付きの申請書を申請していきます！
コラボフローを使うことで、社内の申請書類をブラウザ等の画面上で申請することができますが、

社内のシステム等から、コラボフローのAPIを実行し、申請を行うこともできます。
今回紹介するのはほんの一例ですが、コラボフローAPIを触ってみたい方やコラボフロー開発をされているシステム担当の方、パートナーの方などなど、ぜひご参考になれば嬉しいです！
🔻コラボフローAPIドキュメント

https://docs.collaboflow.com/api-docs/#/

 事前準備あらかじめ、コラボフローのお試し環境を準備いただき、Node.js をインストールします。

Node.js の導入は以下のような記事が参考になりそうですね。

https://qiita.com/sefoo0104/items/0653c935ea4a4db9dc2b
ご自身のローカルに Node.js が入っているかどうかは、コマンドプロンプトやターミナル等にて確認することができます。
$ node -v
以下のようにバージョンが表示されれば問題ないです。
v22.9.0

 フォームの作成コラボフローにフォームを登録する必要がありますので、手順に沿ってフォームを作成します。



 経路の作成フォームは完成しましたが、これを経路に紐づける必要がありますので、

手順に沿って、経路を作成していきます。
必要であれば、経路アイテムを配置するなど、ご自身で設定いただくことができます。


 プロジェクトの作成続いて、コラボフローAPIを実行し、添付ファイル付き申請書を送信するための準備を行なっていきます！

ローカルに、任意の作業フォルダを作成します。
$ mkdir collaboflow-2024
$ cd collaboflow-2024
さらに以下を実行し、package.jsonファイルを作成します。
$ npm init -y
作成された package.jsonを以下のように変更を加えます。

※今回は、ES Module に対応したコードを用意してきましたので本作業が発生します。
package.json
{
  "name": "collaboflow-advent",
  "version": "1.0.0",
  "main": "index.js",
+ "type": "module", // 追加します
}

 axios のインストール最後に、必要なライブラリとして、Axiosをインストールしておきます。

Node からコラボフローへのAPI通信のため、Axiosを利用します。
🔻Axios

https://axios-http.com/ja/docs/intro
以下コマンドで Axiosのインストールが完了です。
$ npm i axios

 プログラムの実装、実行
 ファイル作成、コードのコピー最後に、いよいよ本題であるプログラムの実装と、実行です。

index.jsファイルを、ルートディレクトリに作成し、以下のサンプルコードをコピーします。
index.js
import axios from 'axios';
import FormData from 'form-data';
import fs from 'fs';

// ベースのURL
const baseUrl = 'https://cloud.collaboflow.com/{xxxxx}/api/index.cfm/v1';

// ログインID/apikey:発行されたAPIキーを符号化したキー
// @see https://docs.collaboflow.com/api-docs/#/
const apiKey = '{xxxxxxxxx}';

// 経路ID
const processesId = {xxxxx}; // 例) 1

// アプリケーションコード
const appCd = {xxxxx}; // 例) 1

// ファイルの相対パス
const filePath = '{xxxxx}'; // 例) '休暇届.pdf'

// ヘッダーを生成
const headers = {
    'X-Collaboflow-Authorization': `Basic ${apiKey}`
};

/**
 * ファイルをアップロードする関数
 * @param {string} filePath - アップロードするファイルのパス
 * @returns {Promise} - アップロードされたファイルのIDを含むレスポンス
 */
async function uploadFile(filePath) {
    const fileUrl = `${baseUrl}/files`;
    const formData = new FormData();
    formData.append('file', fs.createReadStream(filePath));
    
    try {
        const response = await axios.post(fileUrl, formData, {
            headers: {
                ...headers,
                ...formData.getHeaders()
            }
        });
        
        if (response.status !== 201) {
            throw new Error('ファイルの登録に失敗しました。' + response.statusText);
        }
        
        return response.data;
    } catch (error) {
        console.error('ファイルの登録に失敗しました。', error);
        throw error;
    }
}

/**
 * ドキュメント申請を行う関数
 * @param {string} fileId - アップロードされたファイルのID
 * @returns {Promise} - 申請のレスポンス
 */
async function submitDocument(fileId) {
    const documentUrl = `${baseUrl}/documents`;
    const payload = {
        processes_id: processesId,
        app_cd: appCd,
        document: {
            fidAttachment: fileId
        }
    };

    try {
        const response = await axios.post(documentUrl, payload, { headers });
        
        if (response.status !== 201) {
            throw new Error('ファイルの登録に失敗しました。' + response.statusText);
        }
        
        return response.data;
    } catch (error) {
        console.error('申請に失敗しました。', error);
        throw error;
    }
}

/**
 * メイン処理
 */
async function main() {
    try {
        const fileData = await uploadFile(filePath);
        console.log('ファイルがアップロードされました。', fileData);
        
        const documentData = await submitDocument(fileData.id);
        console.log('申請が完了しました。', documentData);
    } catch (error) {
        console.error('処理中にエラーが発生しました。', error);
    }
}

// メイン処理を実行
main();

 添付ファイルの配置index.jsを配置した同階層に、今回、コラボフローで添付したいファイルを配置しておきます。

以下のように、sample.pdfのようなファイルがあることを確認しておきます。


 コードの書き換えindex.jsのコメントアウトが記載されている項目をご自身で書き換えていただく必要があります。

以下をご参考に、コード部分の書き換えを実施ください！
ベースのURL
{xxxxx}の部分にコラボフローのインスタンス名を入れてください。
参考記事: https://collaboflow.zendesk.com/hc/ja/articles/4425823538575


ログインID/apikey:発行されたAPIキーを符号化したキー
{xxxxx}の部分に ログインID/apikey:発行されたAPIキーを符号化したものを入れてください。
参考記事: https://collaboflow.zendesk.com/hc/ja/articles/360000262636


経路ID
{xxxxx}の部分に作成した経路IDを入れてください。
参考記事: https://collaboflow.zendesk.com/hc/ja/articles/360000419536


アプリケーションコード
{xxxxx}の部分作成したフォームや、経路のあるアプリケーションコードを入れてください。
参考記事: https://collaboflow.zendesk.com/hc/ja/articles/360000266595


ファイルの相対パス
{xxxxx}の部分にファイル名を入れてください。


 コードの実行すべての書き換えが終わり、添付したいファイルがある状態で、いよいよ実行です！

以下のコマンドで実行することができます。
$ node index.js
成功すると、以下のように出力されます👏
ファイルがアップロードされました。 {
  craeted_at: '2024-12-09T01:44:20Z',
  content_type: 'application/pdf',
  size: 113157,
  link: 'https://cloud.collaboflow.com/xxxxx/api/index.cfm/v1/files/-yXtMW9DOPxGsI2uY7Emh38__u3DVowf8IWJI43pEr2u/download',
  error: false,
  id: '-yXtMW9DOPxGsI2uY7Emh38__u3DVowf8IWJI43pEr2u',
  filename: 'sample.pdf'
}
申請が完了しました。 {
  document_number: '200-000002',
  represent_usercd: '',
  request_groupname: '管理部',
  app_cd: 4,
  flow_status: 'decision',
  end_date: '2024-12-09T01:44:21Z',
  represent_username: '',
  form_version: 1,
  request_usercd: '00000000000000000000000000000000',
  request_groupcd: 'B6CB1B8FC6A246AAC16A4307EBC1E6A5',
  request_date: '2024-12-09T01:44:21Z',
  document_id: 3120,
  request_username: 'システム管理者',
  link: 'https://cloud.collaboflow.com/xxxxx/index.cfm?app_cd=4&fuseaction=clz_DocumentDesc&nPInstanceCD=3120',
  error: false,
  title: '2024コラボフローアドベントカレンダー',
  request_titles: [],
  form_id: 129,
  processes_id: 200
}
コラボフローでも申請されていることがか確認できました！

※ファイル名が若干違うのは諸事情です、、許して、、


 おわりにコラボフローのAPIを使い、添付ファイルの操作を行うことは若干クセのある実装をする必要があります。

これが理解できればコラボフローのAPIは全く怖くない！と言っても過言ではないので、ぜひコードを最後まで読んで、理解を深めていただければと思います。
では！