Route claims evidence for review with Box Automate

mkdir claims-evidence-review && cd claims-evidence-review

python3 -m venv .venv
source .venv/bin/activate

pip install box-sdk-gen flask python-dotenv

BOX_CLIENT_ID=your_client_id
BOX_CLIENT_SECRET=your_client_secret
BOX_USER_ID=your_managed_user_id
BOX_CLAIMS_FOLDER_ID=your_claims_review_folder_id
BOX_CLAIMS_TEMPLATE_KEY=your_metadata_template_key
BOX_CLAIMS_WORKFLOW_NAME=Claims evidence review

import os

from box_sdk_gen import BoxCCGAuth, BoxClient, CCGConfig
from dotenv import load_dotenv

load_dotenv()


def get_box_client() -> BoxClient:
    config = CCGConfig(
        client_id=os.getenv("BOX_CLIENT_ID"),
        client_secret=os.getenv("BOX_CLIENT_SECRET"),
        user_id=os.getenv("BOX_USER_ID"),
    )
    return BoxClient(auth=BoxCCGAuth(config=config))

from dataclasses import dataclass

from box_sdk_gen import BoxClient
from box_sdk_gen.networking.fetch_options import FetchOptions, ResponseFormat

BOX_API_BASE = "https://api.box.com/2.0"
AUTOMATE_HEADERS = {"box-version": "2026.0"}

MAX_FILES_PER_RUN = 20


@dataclass(frozen=True)
class WorkflowAction:
    """A published Automate workflow that can be started through the API."""

    workflow_id: str
    action_id: str
    name: str


def list_workflow_actions(client: BoxClient, folder_id: str) -> list[WorkflowAction]:
    response = client.make_request(
        FetchOptions(
            url=f"{BOX_API_BASE}/automate_workflows",
            method="GET",
            params={"folder_id": folder_id},
            headers=AUTOMATE_HEADERS,
            response_format=ResponseFormat.JSON,
        )
    )

    return [
        WorkflowAction(
            workflow_id=entry["workflow"]["id"],
            action_id=entry["id"],
            name=entry["workflow"].get("name", ""),
        )
        for entry in response.data.get("entries") or []
    ]


def find_workflow_action(
    client: BoxClient, folder_id: str, workflow_name: str
) -> WorkflowAction:
    actions = list_workflow_actions(client, folder_id)

    if not actions:
        raise LookupError(
            f"No Automate workflow actions on folder {folder_id}. Confirm the "
            "workflow is published and its Manual Start trigger uses this folder."
        )

    for action in actions:
        if action.name == workflow_name:
            return action

    available = ", ".join(sorted(action.name for action in actions))
    raise LookupError(
        f"Workflow {workflow_name!r} not found on folder {folder_id}. "
        f"Available workflows: {available}."
    )


def start_workflow(
    client: BoxClient, action: WorkflowAction, file_ids: list[str]
) -> None:
    client.make_request(
        FetchOptions(
            url=f"{BOX_API_BASE}/automate_workflows/{action.workflow_id}/start",
            method="POST",
            headers=AUTOMATE_HEADERS,
            data={"workflow_action_id": action.action_id, "file_ids": file_ids},
            response_format=ResponseFormat.JSON,
        )
    )

import os

from box_sdk_gen import (
    BoxAPIError,
    BoxClient,
    CreateFileMetadataByIdScope,
    UpdateFileMetadataByIdRequestBody,
    UpdateFileMetadataByIdRequestBodyOpField,
    UpdateFileMetadataByIdScope,
)
from dotenv import load_dotenv

load_dotenv()

HTTP_CONFLICT = 409


def tag_evidence(client: BoxClient, file_ids: list[str], claim_id: str) -> None:
    """Attach claim context to each evidence file so the workflow can read it."""
    template_key = os.getenv("BOX_CLAIMS_TEMPLATE_KEY")
    values = {"claimId": claim_id, "reviewStatus": "in_review"}

    for file_id in file_ids:
        try:
            client.file_metadata.create_file_metadata_by_id(
                file_id=file_id,
                scope=CreateFileMetadataByIdScope.ENTERPRISE,
                template_key=template_key,
                request_body=values,
            )
        except BoxAPIError as error:
            if error.response_info.status_code != HTTP_CONFLICT:
                raise
            _replace_metadata(client, file_id, template_key, values)


def _replace_metadata(
    client: BoxClient, file_id: str, template_key: str, values: dict[str, str]
) -> None:
    """Overwrite an existing instance, for evidence resubmitted on the same claim."""
    client.file_metadata.update_file_metadata_by_id(
        file_id=file_id,
        scope=UpdateFileMetadataByIdScope.ENTERPRISE,
        template_key=template_key,
        request_body=[
            UpdateFileMetadataByIdRequestBody(
                op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,
                path=f"/{key}",
                value=value,
            )
            for key, value in values.items()
        ],
    )

import os

from dotenv import load_dotenv
from flask import Flask, jsonify, request

from automate import MAX_FILES_PER_RUN, find_workflow_action, start_workflow
from box_client import get_box_client
from claims_metadata import tag_evidence

load_dotenv()
app = Flask(__name__)


@app.post("/reviews")
def start_review():
    payload = request.get_json(silent=True) or {}
    claim_id = payload.get("claim_id")
    file_ids = payload.get("file_ids") or []

    if not claim_id:
        return jsonify({"error": "claim_id is required"}), 400
    if not file_ids:
        return jsonify({"error": "file_ids must list at least one file"}), 400
    if len(file_ids) > MAX_FILES_PER_RUN:
        return jsonify(
            {"error": f"Box Automate accepts at most {MAX_FILES_PER_RUN} files per run"}
        ), 400

    client = get_box_client()
    folder_id = os.getenv("BOX_CLAIMS_FOLDER_ID")
    workflow_name = os.getenv("BOX_CLAIMS_WORKFLOW_NAME")

    tag_evidence(client, file_ids, claim_id)

    action = find_workflow_action(client, folder_id, workflow_name)
    start_workflow(client, action, file_ids)

    return jsonify(
        {
            "status": "review_started",
            "claim_id": claim_id,
            "workflow": action.name,
            "file_ids": file_ids,
        }
    ), 202


if __name__ == "__main__":
    app.run(port=5000)

claims-evidence-review/
├── .env
├── .venv/
├── app.py
├── automate.py
├── box_client.py
└── claims_metadata.py