Box.orgのためのBox Platformの使用について

Published in

Box Developer Japan Blog

13 min readMay 10, 2024

最近、私はBox.orgと一緒に仕事をする機会がありました。Box.orgとは、私たち (Box社員) が仕事を通じて社会的な影響や変革を推進するBoxの組織で、Boxには欠かせない、多方面にわたるすばらしい組織です。これまで、Box Impact Fundの申請プロセスには、手作業によるデータ入力など、時間のかかる手順が必要でした。そこで、Box SDKの1つを使用して、データを分析してCSVに抽出するスクリプトを作成することで、Box.orgチーム全体で共有される追跡用のGoogleスプレッドシートに管理者が新しいエントリを追加できるようにしました。この記事では、ソリューションの概要を説明するほか、このプロセスの管理や手作業の削減に役立つ可能性のあるBox API Platformの他の部分に関するアイデアやプロトタイプも紹介します。

申請プロセスの基本的な流れは以下のとおりです。

慈善団体は、Boxに申請書を提出することで、Box Impact Fundの助成金を申請できます。これは、Boxユーザーであれば誰でも構成および設定可能なファイルリクエストリンクを介して行われ、社外ユーザーから安全かつ簡単にコンテンツを受け取るための優れた方法となります。
申請者は、申請書と共に簡単なビデオを提出して、慈善団体に関する詳細な状況と、支給された場合にBox助成金をどのように有効活用するかを提示します。これは、ビデオと一緒に、指定されたBoxフォルダ内のBoxメタデータテンプレートに保存されます。申請書に対してタスクが自動的に作成されます。
Box社員の選抜チームが、ステップ2で生成されたタスクに基づいて申請書を審査し、最も優れた申請書を次の段階に進めます。次の段階では、さらに詳細な査定によって12の最終候補に絞り込まれます。
業界の専門家と数人のBox社員で構成された審査委員会が、助成金を受ける最終的な6団体を選出します。Box Impact Fundと審査委員会の詳細はこちらをご覧ください。

審査と承認のタスクはすべて、直感的なワークフローツールであるBox Relayで行われます。Box Relayでは、BoxユーザーがBoxウェブアプリで直接ワークフローを構成できます。このRelayワークフローは、ユーザーがファイルリクエストリンクを使用してアップロードしたときにタスクを作成するよう構成されています。

Relayのタスクで、Boxに保存されているGoogleスプレッドシートを使用して、Box.orgのメンバーがすべての申請書 (関連付けられたメタデータを含む) を表示できるようにします。また、BoxはGoogleスプレッドシートでの共同編集をサポートしているため、メンバーは各申請書に移動して、申請書を確認すると同時に採点することも可能になります。

現在、このプロセスは次のようになっています。

申請書を抽出するスクリプト

ここが私が初めて支援した場所です。Box.orgチームは、申請者のドキュメントとメタデータをトラッカーであるGoogleスプレッドシートに取り込み、さらにこれを自動化する必要がありました。当時は締め切りが厳しかったため、私は、Box.orgの管理者が新規の申請書をトラッカーであるGoogleスプレッドシートに転送するためのCSVファイルを生成するこのスクリプトを作成しました。この申請プロセスでは1つのファイルを要求しますが、申請者によっては複数のファイルをアップロードする場合もあるため、このスクリプトでは、申請書フォルダ内の一意の申請書で構成されるCSVが作成されます。このスクリプトは、BoxのJava SDKを使用して記述され、コマンドラインから呼び出すことができるシンプルなjarとして作成されているため、担当の管理者は新しい申請書を抽出するタイミングを柔軟に決定できます。

申請書の収集に使用されるファイルリクエストは、関連するメタデータを含む申請用ビデオファイルをすべて、Boxのランディングフォルダに保存します。このスクリプトは、そのフォルダ内のすべてのファイルを反復処理して、(メールアドレスに基づいて) 一意の申請者ごとに1行を出力し、メタデータや、Box内の申請書を開くためのリンクを含めます。

こちらのGitHubリポジトリにあるmavenプロジェクトを使用すると、jarファイルを設定してビルドし、実行することができます。

出力のサンプルを次に示します。その後、これをトラッカーのスプレッドシートに直接貼り付けることができます。

今後 -> BoxメタデータクエリUI

プロセス全体をサポートするための次のステップでは、申請書を表示してタスクを処理するためのUIベースのアプローチを提供します。また、トラッカー用にCSVファイルをエクスポートするオプションも追加したため、Box.orgの管理者チームがターミナルを使用してこの処理を行う必要はありません。

これを実現するために、Box UI Elementsを使用してプロトタイプのメタデータクエリフィルタUIを作成します。BoxメタデータクエリAPIを使用すると、メタデータの条件に基づいてすべてのファイルを照会し、このプロトタイプで使用されるフィルタ (クエリパラメータを使用) を許可することができます。Box UI Elementsは、カスタムアプリケーションからBoxの機能を簡単に利用できるようにするJavaScriptウィジェットです。詳細については、UI Elementsのワークショップ (英語)、ReactでのUI Elements、メタデータクエリAPI、メタデータクエリとUI Elementsに関する記事をご覧ください。

また、このプロトタイプでは、コマンドラインターミナルでエクスポートする必要なく、インターフェースから直接CSVをエクスポートする機能も提供します。そのために、クリックしたときに現在のクエリを実行し、その結果を動的に生成されたCSVファイルにエクスポートするボタンを用意しています。

上部にあるボタンを使用すると、ユーザーは申請の段階 (「Not Screened (未審査)」、「Rejected (却下)」、「Second Stage (第2段階)」、「Finalist (最終選考)」) でフィルタをかけることができます。また、結果のウィンドウでは、申請用ビデオを直接プレビューし、同じウィンドウからBox Relayタスクを操作できます。これは、ユーザーがメインのGoogleスプレッドシートトラッカーを開くことなく既存の申請書にフィルタをかけて、概要を知りたい場合に便利です。

UI Elementで読み込むメタデータクエリを取得するには、クエリで返されるようにするメタデータフィールド、クエリ定義自体、アプリでユーザーに表示するフィールドを定義します。

フィールドには、ファイルのプロパティと、1つのメタデータテンプレートの特定のメタデータフィールドの両方を指定できます。以下の例では、「created_at」、「name」、「uploader_display_name」がファイルの基本的なプロパティであるのに対し、「metadata…」で始まるフィールドは、ファイルリクエストを使用して申請書を提出した申請者が入力したメタデータフィールドです (EIDは、APIの接続先となるBoxインスタンスの一意のIDを指します。これは、Box開発者コンソールのアプリの [一般設定] で取得できます。

fields=[
"created_at",
"name",
"uploader_display_name",
"metadata.enterprise_<eid>.boxImpactFundApplication.applicantName",
"metadata.enterprise_<eid>.boxImpactFundApplication.approvalStage","metadata.enterprise_47757585.boxImpactFundApplication.organizationName",
"metadata.enterprise_<eid>.boxImpactFundApplication.organisationCategory",
"metadata.enterprise_<eid>.boxImpactFundApplication.totalBudgetFromLastYear",
"metadata.enterprise_<eid>.boxImpactFundApplication.regions"]

クエリ定義は次のようになります。ここでは、使用するメタデータテンプレート、クエリ文字列、クエリのベースとなるフォルダ、上記で定義したフィールドを定義します。

mdQuery = {
    //The from field specifies the metadata template to query
    from: "enterprise_<eid>.boxImpactFundApplication",
    //The query filters the results
    query: "approvalStage1=:approvalStageArg",
    //Limit the number of results returned (more results can be fetched using marker based pagination)
    limit: 100,
    //The query parameters for the query filter - in this case approval stage
    query_params: {"approvalStageArg":approvalStage},
    //The Box Folder id of the application folder
    ancestor_folder_id: <folder to start the query from>,
    //An array of fields to fetch 
    fields: fields
};

UI Elementでクエリの結果を表示するには、表示するフィールドを定義します。その際、ここで参照される任意のフィールドは、上記のフィールドのデータで定義されている必要があることに注意してください。ここでは、ファイルのプロパティとメタデータフィールドの両方を追加したり、表示名を指定したり、フィールドのインライン編集を許可したりすることができます。これはこのプロトタイプでは必要ありませんが、多くのユースケースに役立ちます。

const fieldsToShow = [
  { key: 'created_at', displayName:'Submission Date',canEdit: false },
  { key: 'uploader_display_name', displayName:'Email',canEdit: false },
  { key: 'metadata.enterprise_<eid>.boxImpactFundApplication.applicantName',displayName:'Applicant Name', canEdit: false },
  { key: 'metadata.enterprise_<eid>.boxImpactFundApplication.organizationName',displayName:'Organization Name',  canEdit: false },
  { key: 'metadata.enterprise_<eid>.boxImpactFundApplication.organisationCategory',displayName:'Organization Category',  canEdit: false },
  { key: 'metadata.enterprise_<eid>.boxImpactFundApplication.totalBudgetFromLastYear',displayName:'Last years budget',  canEdit: false },
  { key: 'metadata.enterprise_<eid>.boxImpactFundApplication.regions',displayName:'Regions',  canEdit: false },
];

上記のパーツをまとめて表示するため、コンテンツエクスプローラUI Elementを使用します。これには、通常、フォルダのコンテンツが表示されますが、「defaultView」を「metadata」に設定することで、フォルダのコンテンツではなくメタデータクエリの結果を表示できるようになります。

const defaultView = "metadata";
  contentExplorer.show(boxId, token, {
    container: '#nav-container',
    metadataQuery: mdQuery,
    defaultView: defaultView,
    fieldsToShow:fieldsToShow,
    contentPreviewProps: {
        contentSidebarProps: {
            hasActivityFeed: true,
            hasMetadata: true
        }
    }

ページ、認証、ウェブアプリ統合機能を設定するための一連の手順を含むGitHubリポジトリへのリンクはこちらです。

まとめ

このフローでは、新機能が追加された場合に、管理者と審査担当者の両方がカスタムアプリを使用して申請書にアクセスし、確認、処理するプロセスがどのようになるのかを示しています。Googleスプレッドシートトラッカーには申請書の採点に関するロジックが存在するため、これはプロセスの最後の部分に残しています。

Box.orgチームと協力してプロセスの効率化をお手伝いできて嬉しく思います。今年はさらにプロセスを改善したいと考えています。

アイデア、コメント、フィードバックがある場合は、コミュニティフォーラム (英語のみ) にコメントをお送りください。

Box.orgのためのBox Platformの使用について

申請書を抽出するスクリプト

今後 -> BoxメタデータクエリUI

まとめ

Written by Yuko Taniguchi