Box APIで新規採用者のオンボーディングを自動化する

mkdir onboarding-workspace && cd onboarding-workspace

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_ENTERPRISE_ID=your_enterprise_id
ONBOARDING_ROOT_FOLDER_ID=0

import os
from dotenv import load_dotenv
from box_sdk_gen import (
    BoxClient,
    BoxCCGAuth,
    CCGConfig,
)

load_dotenv()

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

# Maps a logical role key to the actual Box group name.
# Edit the names to match the groups in your enterprise.
GOVERNANCE_GROUPS = {
    "IT": "IT Onboarding",
    "HR": "HR Onboarding",
    "All Employees": "All Employees",
}

# The standardized folder tree created for every new hire.
# `collaborators` grants a governance group access at that exact level.
# Because collaborations cascade, access granted on a folder also
# applies to everything nested inside it.
WORKSPACE_TEMPLATE = {
    "name": "Onboarding",
    "collaborators": [],
    "children": [
        {"name": "Personal", "collaborators": [], "children": []},
        {
            "name": "IT Setup",
            "collaborators": [{"group": "IT", "role": "editor"}],
            "children": [],
        },
        {
            "name": "HR Documents",
            "collaborators": [{"group": "HR", "role": "editor"}],
            "children": [],
        },
        {
            "name": "Policies & Templates",
            "collaborators": [{"group": "All Employees", "role": "viewer"}],
            "children": [],
        },
        {"name": "Team Resources", "collaborators": [], "children": []},
    ],
}

from box_sdk_gen import BoxClient, BoxAPIError

from config import GOVERNANCE_GROUPS

def get_or_create_group(client: BoxClient, name: str) -> str:
    try:
        group = client.groups.create_group(
            name,
            description="Governance group managed by onboarding automation.",
        )
        print(f"Created group '{group.name}' ({group.id})")
        return group.id
    except BoxAPIError as error:
        if error.response_info.status_code != 409:
            raise
        for group in client.groups.get_groups(filter_term=name).entries:
            if group.name == name:
                print(f"Using existing group '{group.name}' ({group.id})")
                return group.id
        raise

def resolve_governance_groups(client: BoxClient) -> dict:
    """Return a map of logical group key -> Box group ID."""
    return {
        key: get_or_create_group(client, name)
        for key, name in GOVERNANCE_GROUPS.items()
    }

from box_sdk_gen import (
    BoxClient,
    BoxAPIError,
    CreateFolderParent,
    CreateCollaborationItem,
    CreateCollaborationItemTypeField,
    CreateCollaborationAccessibleBy,
    CreateCollaborationAccessibleByTypeField,
    CreateCollaborationRole,
)

ROLE_MAP = {
    "editor": CreateCollaborationRole.EDITOR,
    "viewer": CreateCollaborationRole.VIEWER,
    "uploader": CreateCollaborationRole.UPLOADER,
    "co-owner": CreateCollaborationRole.CO_OWNER,
}

def is_already_collaborator(error: BoxAPIError) -> bool:
    # Box reports an existing collaborator differently for groups and users:
    # a group returns 409 with code "conflict", while a user can return
    # "user_already_collaborator". Match on both so re-runs are safe.
    body = error.response_info.body
    message = body.get("message", "").lower()
    return (
        body.get("code") == "user_already_collaborator"
        or "already a collaborator" in message
    )

def create_folder(client: BoxClient, name: str, parent_id: str) -> str:
    try:
        folder = client.folders.create_folder(
            name, CreateFolderParent(id=parent_id)
        )
        return folder.id
    except BoxAPIError as error:
        # 409 means a folder with this name already exists under the parent.
        # Reuse it so re-running the service never creates duplicates.
        if error.response_info.status_code != 409:
            raise
        conflicts = error.response_info.body.get("context_info", {}).get(
            "conflicts", []
        )
        return conflicts[0]["id"]

def add_group_collaboration(
    client: BoxClient, folder_id: str, group_id: str, role: str
):
    try:
        client.user_collaborations.create_collaboration(
            item=CreateCollaborationItem(
                type=CreateCollaborationItemTypeField.FOLDER, id=folder_id
            ),
            accessible_by=CreateCollaborationAccessibleBy(
                type=CreateCollaborationAccessibleByTypeField.GROUP, id=group_id
            ),
            role=ROLE_MAP[role],
        )
    except BoxAPIError as error:
        # Ignore if the group is already a collaborator on this folder.
        if not is_already_collaborator(error):
            raise

def build_workspace(
    client: BoxClient, node: dict, parent_id: str, group_ids: dict
) -> str:
    folder_id = create_folder(client, node["name"], parent_id)

    for collaborator in node.get("collaborators", []):
        group_id = group_ids[collaborator["group"]]
        add_group_collaboration(
            client, folder_id, group_id, collaborator["role"]
        )
        print(
            f"  Shared '{node['name']}' with "
            f"{collaborator['group']} ({collaborator['role']})"
        )

    for child in node.get("children", []):
        build_workspace(client, child, folder_id, group_ids)

    return folder_id

import os
from dotenv import load_dotenv
from box_sdk_gen import (
    BoxClient,
    BoxAPIError,
    CreateCollaborationItem,
    CreateCollaborationItemTypeField,
    CreateCollaborationAccessibleBy,
    CreateCollaborationAccessibleByTypeField,
    CreateCollaborationRole,
)

from box_client import get_box_client
from config import WORKSPACE_TEMPLATE
from groups import resolve_governance_groups
from workspace import build_workspace, is_already_collaborator

load_dotenv()

def invite_new_hire(client: BoxClient, folder_id: str, login: str):
    """Give the new hire access to their workspace root.

    Co-owner is used when the service account owns the folder. Otherwise we
    fall back to editor, because only owners and co-owners can grant co-owner.
    """
    me = client.users.get_user_me()
    folder = client.folders.get_folder_by_id(folder_id, fields=["owned_by"])
    if folder.owned_by and folder.owned_by.id == me.id:
        role = CreateCollaborationRole.CO_OWNER
    else:
        role = CreateCollaborationRole.EDITOR

    try:
        client.user_collaborations.create_collaboration(
            item=CreateCollaborationItem(
                type=CreateCollaborationItemTypeField.FOLDER, id=folder_id
            ),
            accessible_by=CreateCollaborationAccessibleBy(
                type=CreateCollaborationAccessibleByTypeField.USER, login=login
            ),
            role=role,
        )
        print(f"Invited {login} to workspace {folder_id} as {role.value}")
    except BoxAPIError as error:
        if not is_already_collaborator(error):
            raise

def onboard_new_hire(hire: dict) -> str:
    client = get_box_client()

    group_ids = resolve_governance_groups(client)

    template = dict(WORKSPACE_TEMPLATE)
    template["name"] = f"{hire['name']} - Onboarding"

    parent_id = os.getenv("ONBOARDING_ROOT_FOLDER_ID", "0")
    workspace_id = build_workspace(client, template, parent_id, group_ids)

    if hire.get("email"):
        invite_new_hire(client, workspace_id, hire["email"])

    print(f"Workspace ready for {hire['name']} (ID: {workspace_id})")
    return workspace_id

if __name__ == "__main__":
    # Simulate a hire event for a quick local test.
    onboard_new_hire({"name": "Jordan Rivera", "email": None})

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

from onboarding import onboard_new_hire

load_dotenv()
app = Flask(__name__)

@app.route("/hire", methods=["POST"])
def handle_hire_event():
    event = request.get_json()

    if event.get("event") != "employee.hired":
        return jsonify({"status": "ignored"}), 200

    employee = event["employee"]
    hire = {
        "name": employee["full_name"],
        "email": employee.get("work_email"),
    }

    workspace_id = onboard_new_hire(hire)

    return jsonify({"status": "provisioned", "workspace_id": workspace_id}), 200

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

onboarding-workspace/
├── .env
├── .venv/
├── app.py
├── box_client.py
├── config.py
├── groups.py
├── onboarding.py
└── workspace.py

cd ~/onboarding-workspace
source .venv/bin/activate
python3 app.py

* Running on http://127.0.0.1:5000

curl -X POST http://127.0.0.1:5000/hire \
  -H "Content-Type: application/json" \
  -d '{
    "event": "employee.hired",
    "employee": {
      "full_name": "Jordan Rivera",
      "work_email": "jordan.rivera@example.com"
    }
  }'

Created group 'IT Onboarding' (12345678)
Created group 'HR Onboarding' (12345679)
Created group 'All Employees' (12345680)
  Shared 'IT Setup' with IT (editor)
  Shared 'HR Documents' with HR (editor)
  Shared 'Policies & Templates' with All Employees (viewer)
Invited jordan.rivera@example.com to workspace 98765432
Workspace ready for Jordan Rivera (ID: 98765432)

from box_client import get_box_client

client = get_box_client()

# Replace with the workspace_id returned by the service.
workspace_id = "98765432"

for folder in client.folders.get_folder_items(workspace_id).entries:
    print(folder.type, folder.id, folder.name)
    collaborations = client.list_collaborations.get_folder_collaborations(folder.id)
    for collaboration in collaborations.entries:
        print(f"  {collaboration.accessible_by.name} - {collaboration.role.value}")