FileVault Integration Guide

Practical integration guide for services that consume FileVault.

1. Integration Contract

• Base URL (example): https://filevault.denning.online
• Server-scoped base: /api/v1/{server_code}
• Auth token header:
  • Authorization: Bearer fv_<token>
  • or X-API-Token: fv_<token>
• Caller identity header (recommended):
  • X-User-Email: <identity>
  • Denning services should send staffCode in this header.

2. Path Rules (Strict)

Do not send server_code inside path values.

Valid path formats:

• Module-based: {module}/{recordId}/{sub_path}/{filename}
• Documents module: documents/{sub_path}/{filename} (no recordId)

Examples:

• matters/12345/evidence/contract.pdf
• staff/101/avatar/photo.jpg
• documents/policies/leave-policy.pdf

Invalid:

• TS0004/matters/12345/contract.pdf
• /matters/12345/contract.pdf
• documents/12345/file.pdf

3. Access Levels and Metadata

The metadata field on upload controls file visibility and ownership tracking. It is optional — if omitted, the file defaults to access_level: "server" (visible to all firm users) and uploaded_by: "system".

Metadata fields:

• uploaded_by — staff code or email of uploader (default: "system")
• access_level — file visibility (default: "server"):
  • "server" — everyone in the same firm/tenant can see it
  • "private" — only the uploader can see it
  • "public" — anyone with the link

4. Core Path-Based Operations

Upload

Upload fields:

• file (required) — the file to upload
• path (required) — destination path, e.g. matters/12345/document.pdf
• metadata (optional JSON string) — see Access Levels and Metadata above
• overwrite (optional boolean, default true) — replace existing file at same path

Minimal example (most common — all firm users can see):

curl -X POST "https://filevault.denning.online/api/v1/TS0004/storage/upload" \
  -H "Authorization: Bearer fv_your_token" \
  -H "X-User-Email: ST0001" \
  -F "file=@document.pdf" \
  -F "path=matters/12345/document.pdf"

With metadata (restrict to uploader only):

curl -X POST "https://filevault.denning.online/api/v1/TS0004/storage/upload" \
  -H "Authorization: Bearer fv_your_token" \
  -H "X-User-Email: ST0001" \
  -F "file=@document.pdf" \
  -F "path=matters/12345/document.pdf" \
  -F 'metadata={"uploaded_by":"ST0001","access_level":"private"}'

Note: If you skip metadata, the file defaults to access_level: "server" (visible to all firm users) and uploaded_by: "system".

Download

curl "https://filevault.denning.online/api/v1/TS0004/storage/download?path=matters/12345/document.pdf" \
  -H "Authorization: Bearer fv_your_token" \
  -H "X-User-Email: ST0001" \
  -o document.pdf

Lookup (metadata)

curl "https://filevault.denning.online/api/v1/TS0004/storage/lookup?path=matters/12345/document.pdf" \
  -H "Authorization: Bearer fv_your_token" \
  -H "X-User-Email: ST0001"

List

curl "https://filevault.denning.online/api/v1/TS0004/storage/list?directory=matters/12345&recursive=false&per_page=100" \
  -H "Authorization: Bearer fv_your_token" \
  -H "X-User-Email: ST0001"

Exists

Check if a file exists:

curl "https://filevault.denning.online/api/v1/TS0004/storage/exists?path=matters/12345/document.pdf" \
  -H "Authorization: Bearer fv_your_token"

Check if a directory/folder exists (pass type=directory):

curl "https://filevault.denning.online/api/v1/TS0004/storage/exists?path=matters/12345&type=directory" \
  -H "Authorization: Bearer fv_your_token"

Response:

{ "status": "success", "exists": true, "path": "matters/12345", "type": "directory" }

Delete

curl -X DELETE "https://filevault.denning.online/api/v1/TS0004/storage" \
  -H "Authorization: Bearer fv_your_token" \
  -H "Content-Type: application/json" \
  -d '{"path":"matters/12345/document.pdf"}'

5. Bulk Operations (Path-Based)

Use these for cross-file operations. Responses may be:

• status: success (all passed)
• status: partial (some failed; inspect data.errors)

Bulk Copy

paths[] accepts both files AND folders. Folders are copied recursively to {target_path}/{basename}. Per-file collisions at the destination are skipped (reported under data.errors) — existing files are never overwritten.

# Mixed files + folder, single request
curl -X POST "https://filevault.denning.online/api/v1/TS0004/storage/bulk-copy" \
  -H "Authorization: Bearer fv_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["matters/12345/a.pdf", "matters/12345/evidence"],
    "target_path": "matters/67890"
  }'

Guards that return 422:

• A path equals target_path/{basename} (same source and destination).
• A folder would be copied into itself or into its own subtree.

Bulk Move

curl -X POST "https://filevault.denning.online/api/v1/TS0004/storage/bulk-move" \
  -H "Authorization: Bearer fv_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["matters/12345/draft1.pdf", "matters/12345/draft2.pdf"],
    "target_path": "matters/12345/final"
  }'

Bulk Delete

curl -X POST "https://filevault.denning.online/api/v1/TS0004/storage/bulk-delete" \
  -H "Authorization: Bearer fv_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["matters/12345/old1.pdf", "matters/12345/old2.pdf"]
  }'

6. Tenant Storage Provider Management

Each tenant (server_code) can store multiple provider configs and activate one.

Supported providers:

• system, s3, azure, gcp, alibaba, ftp, sftp, local

List configs

curl "https://filevault.denning.online/api/v1/TS0004/storage/configs" \
  -H "Authorization: Bearer fv_your_token"

Add config

curl -X POST "https://filevault.denning.online/api/v1/TS0004/storage/configs" \
  -H "Authorization: Bearer fv_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "s3",
    "name": "Tenant S3",
    "config": {
      "bucket": "tenant-bucket",
      "region": "ap-southeast-1",
      "key": "AKIA...",
      "secret": "..."
    },
    "activate": false
  }'

Activate provider

curl -X POST "https://filevault.denning.online/api/v1/TS0004/storage/configs/s3/activate" \
  -H "Authorization: Bearer fv_your_token"

7. Storage Migration

Migration is async and requires queue workers.

Start migration

curl -X POST "https://filevault.denning.online/api/v1/TS0004/storage/migration/start" \
  -H "Authorization: Bearer fv_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "source_provider": "system",
    "destination_provider": "s3",
    "activate_destination": true,
    "overwrite_existing": false
  }'

Check status

curl "https://filevault.denning.online/api/v1/TS0004/storage/migration/status" \
  -H "Authorization: Bearer fv_your_token"

Retry failed files

curl -X POST "https://filevault.denning.online/api/v1/TS0004/storage/migration/{migrationId}/retry" \
  -H "Authorization: Bearer fv_your_token"

8. Retry and Failure Handling

Recommended client strategy:

1. Retry network/5xx errors with exponential backoff.
2. Do not retry 4xx validation/permission errors without fixing payload/identity.
3. For bulk operations, read data.errors and retry only failed paths.
4. For migration, use:
   • GET /storage/migration/status
   • GET /storage/migration/jobs
   • POST /storage/migration/{migrationId}/retry

Idempotency notes:

• upload is replace-by-default (overwrite=true default).
• move and bulk-move are not safe to blind-retry unless you verify source/destination state.
• delete and bulk-delete should re-check with exists or list.

9. Template Generation

FileVault generates merged documents from a matter's data. Use the unified /templates/document endpoint — one call, with a dynamic engine switch that lets the firm migrate from the legacy engine to the native one with no caller change.

# Unified endpoint — engine chosen dynamically. Returns the document bytes.
# Only `format` changes between doc / docx / pdf.
curl -X POST "$BASE/api/v1/$SC/templates/document" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"file_no":"6000-6293","report_code":"11367","version_id":"1",
       "language":"B.M.","format":"docx","staff_code":"164"}' \
  -o document.docx

• engine (optional): auto (default) uses the native engine when the template is mapped, else legacy gdwmm; legacy forces gdwmm (100% legacy-identical); native forces the PHP engine.
• report_code = cboTemplate.ReportCode (numeric). doc_type optional — auto-derived. language = English|B.M. format = doc|docx|pdf|xls|xlsx|png|txt (pdf/doc are LibreOffice-converted from the native docx).
• staff_code is required — it becomes webuser-id; an empty value is rejected upstream (HTTP 406 → returned as a 422).
• Response header X-Generator = legacy:gdwmm or native. Add ?meta=1 for JSON {format, bytes, source}.
• ?encoding=base64 (or base64=1): returns the document base64-encoded inside JSON instead of streaming raw bytes — { status, format, mime, filename, bytes, base64, source }. Use this if your HTTP/WCF stack mangles a raw binary body (e.g. reads it as a string) — base64 is text-safe; decode it to get the exact .docx/.pdf. (Mirrors the legacy DenningAPI generate response shape.) Works on /document, /generate, /generate-legacy, /render.
• Direct engines also exist: POST .../templates/generate-legacy (force gdwmm), POST .../templates/generate (force native), POST .../templates/render (native, caller-supplied merge_data, no tenant DB). See API Reference §12.

10. Denning Service Notes

• dp-api and dcc-api should call path-based endpoints (/storage/*) only.
• Send staff identity consistently via X-User-Email using staffCode.
• Keep a valid server_code in service config (example: DCC01) and keep path values server-code-free.

11. Endpoint Summary

FileVault API Reference

Versioned API reference aligned with current routes.

1. Base Paths

• Health: /api/health
• Global: /api/v1
• Server-scoped: /api/v1/{server_code}

{server_code} format: uppercase alphanumeric, 4-20 chars (example: TS0004, DCC01).

2. Authentication

Required for all protected endpoints.

• Authorization: Bearer fv_<64_hex>
• or X-API-Token: fv_<64_hex>

Optional caller identity (used in access checks):

• X-User-Email: <caller-id> (Denning convention: staffCode)

3. Path Validation

Do not include server_code inside path params/body.

Accepted path patterns:

• {module}/{recordId}/{sub_path}/{filename}
• documents/{sub_path}/{filename}

Rejected examples:

• TS0004/matters/123/file.pdf
• /matters/123/file.pdf
• ../../../etc/passwd

4. Common Response Shapes

Success:

{
  "status": "success",
  "message": "Operation completed",
  "data": {}
}

Partial (bulk operations):

{
  "status": "partial",
  "message": "Copied 2 of 3 files",
  "data": {
    "errors": []
  }
}

Error:

{
  "status": "error",
  "message": "Validation failed",
  "errors": {}
}

5. Public and Global Endpoints

Global Module Registry (not server-scoped)

6. Server Endpoints

7. Path-Based Storage Endpoints (Recommended)

7.1 Upload

Multipart form fields:

• file (required) — the file to upload
• path (required) — destination path, e.g. matters/6000-6280/contract.pdf
• metadata (optional JSON string) — controls file visibility and tracking:
  • uploaded_by — staff code or email of uploader (default: "system")
  • access_level — file visibility (default: "server"):
    • "server" — everyone in the same firm/tenant can see it
    • "private" — only the uploader can see it
    • "public" — anyone with the link
• overwrite (optional boolean, default true) — replace existing file at same path

Minimal example (most common — all firm users can see):

curl -X POST "https://filevault.denning.online/api/v1/TS0004/storage/upload" \
  -H "Authorization: Bearer fv_token" \
  -F "file=@contract.pdf" \
  -F "path=matters/12345/evidence/contract.pdf"

With metadata (restrict to uploader only):

curl -X POST "https://filevault.denning.online/api/v1/TS0004/storage/upload" \
  -H "Authorization: Bearer fv_token" \
  -F "file=@contract.pdf" \
  -F "path=matters/12345/evidence/contract.pdf" \
  -F 'metadata={"uploaded_by":"ST0001","access_level":"private"}'

Note: If you skip metadata, the file defaults to access_level: "server" (visible to all firm users) and uploaded_by: "system".

7.2 Read/List

• download query: path
• lookup query: path
• exists query: path, type (optional: file or directory, default: file)
• list query:
  • directory (optional)
  • recursive (optional boolean)
  • per_page (optional, max 100)

7.3 File/Directory Mutations

copy body — works for both files and directories:

{ "source_path": "...", "dest_path": "..." }

Behavior:

• File source → copies to dest_path (must be a full file path). dest_path must NOT already exist (returns 409 Destination already exists); rename upstream if you need to overwrite.
• Directory source → recursively copies every file and sub-directory under source_path to dest_path. Both storage objects and DB rows are duplicated with fresh IDs. Files that already exist at the destination are skipped (not overwritten) and reported in data.errors[].
• Guards: returns 422 if source_path === dest_path, or if dest_path is source_path itself or any path inside it (self-recursion).
• Missing source: returns 404.

Response (file):

{
  "status": "success",
  "message": "File copied successfully",
  "data": { "type": "file", "id": 123, "source_path": "...", "dest_path": "...", "storage_path": "TS0004/..." }
}

Response (directory):

{
  "status": "success",
  "message": "Copied 12 of 12 files (0 skipped) from directory",
  "data": {
    "type": "directory",
    "source_path": "matters/123",
    "dest_path": "matters/456",
    "copied": 12, "skipped": 0, "failed": 0, "total": 12,
    "errors": []
  }
}

If some children fail or are skipped, status becomes "partial" and failures are listed in errors[].

move body (files only today):

{ "source_path": "...", "dest_path": "..." }

rename body:

{ "path": "...", "new_name": "new-file.pdf" }

mkdir body:

{ "path": "...", "access_level": "private", "created_by": "ST0001" }

rmdir body:

{ "path": "..." }

delete body:

{ "path": "..." }

7.4 Archive

compress body:

{
  "paths": ["matters/123/a.pdf", "matters/123/b.pdf"],
  "archive_name": "archive.zip",
  "dest_path": "matters/123/archives"
}

extract body:

{
  "path": "matters/123/archives/archive.zip",
  "dest_path": "matters/123/extracted"
}

7.5 Sharing

share body:

{
  "path": "matters/123/contract.pdf",
  "expires_at": "2026-03-01T00:00:00Z",
  "password": "1234",
  "download_limit": 10
}

7.6 Bulk

bulk-copy:

{
  "paths": ["matters/123/a.pdf", "matters/123/folder-to-clone"],
  "target_path": "matters/456"
}

Each entry in paths may be a file OR a directory. Files go to {target_path}/{basename}; directories are cloned recursively to {target_path}/{basename}/.... Per-path guards, collision skips, and success/partial status use the same rules as /storage/copy. The response aggregates across all paths:

{
  "status": "success",
  "message": "Copied 14 item(s), skipped 0, failed 0",
  "data": {
    "copied": 14, "skipped": 0, "failed": 0, "total": 2,
    "files": [ { "id": 123, "path": "matters/456/a.pdf", "original_path": "matters/123/a.pdf" } ],
    "directories": [
      { "source_path": "matters/123/folder-to-clone", "dest_path": "matters/456/folder-to-clone",
        "copied": 13, "skipped": 0, "failed": 0 }
    ],
    "errors": []
  }
}

bulk-move (files only today):

{
  "paths": ["matters/123/a.pdf", "matters/123/b.pdf"],
  "target_path": "matters/123/archive"
}

bulk-delete:

{
  "paths": ["matters/123/a.pdf", "matters/123/b.pdf"]
}

8. Tenant Storage Provider Configuration

Supported providers:

• system, s3, azure, gcp, alibaba, ftp, sftp, local

Create/update payload:

{
  "provider": "s3",
  "config": {},
  "name": "Tenant S3",
  "description": "Primary tenant storage",
  "visibility": "private",
  "driver": "aws_s3",
  "activate": false
}

9. Storage Migration

Start payload:

{
  "source_provider": "system",
  "destination_provider": "s3",
  "delete_source_files": false,
  "overwrite_existing": false,
  "preserve_directory_structure": true,
  "file_pattern": "*.pdf",
  "activate_destination": true
}

Notes:

• One active migration per tenant.
• Migration uses queued jobs; run a queue worker.
• Retry re-queues only failed file IDs.

10. Server-Scoped Module Configuration

11. Legacy Compatibility Endpoints

Still available for older consumers:

For new integrations, use /storage/*.

12. Template Generation

Generate merged documents (conveyancing forms, letters, bills, …) from a matter's data. Use the unified /templates/document endpoint (it picks the engine dynamically); the per-engine endpoints below are for forcing a specific one:

12.0 Unified generate (dynamic engine — recommended)

POST /v1/{server_code}/templates/document

Same body as generate-legacy plus an engine field:

• engine: "auto" (default) — use the native engine when the template is mapped (catalog has a template_path, or one is passed); otherwise fall back to legacy (gdwmm). Templates migrate to native as they gain a mapping — no caller change. The default is set server-side by TEMPLATE_DEFAULT_ENGINE.
• engine: "legacy" — always gdwmm (100% legacy-identical; resolves report_code itself).
• engine: "native" — always the PHP engine (requires a mapped template_path; 422 if unmapped).

This is the single endpoint dp-api/DO should call so the firm can migrate to its own engine gradually.

Response modes (apply to /document, /generate, /generate-legacy, /render):

• default — streams the raw document bytes (Content-Disposition: attachment).
• ?meta=1 — JSON { status, format, bytes, stats, source } (no document body).
• ?encoding=base64 (or base64=1) — JSON { status, format, mime, filename, bytes, base64, source } with the document base64-encoded. Use when the client/WCF stack would corrupt a raw binary body (reading it as a string); base64 is text-safe — decode it to get the exact file. Mirrors the legacy DenningAPI generate response shape.

12.1 Generate (legacy engine — force gdwmm)

POST /v1/{server_code}/templates/generate-legacy

{
  "file_no": "6000-6291",
  "report_code": "11199",
  "version_id": "1",
  "doc_type": "Conveyancing",
  "language": "B.M.",
  "format": "doc",
  "document_name": "16A LPPSA",
  "staff_code": "354"
}

• file_no (required) — matter file number.
• report_code (required) — the template's cboTemplate.ReportCode. The legacy engine resolves the template internally; no template_path or catalog mapping is needed.
• version_id — template version (default 1).
• doc_type — Conveyancing (default), ConveyancingLetter, Litigation, LitigationLetter, LetterDemand, CKHT, Bill, Voucher, Receipt, Payslip, … (a raw DataMapping enum int is also accepted).
• language — English (default) or B.M..
• format — doc (default), docx, pdf, xls, xlsx, png, txt.
• staff_code — required. The logged-in staff code (e.g. 164). Sent as webuser-id / strGCode; an empty value makes the tenant WCF reject the request with HTTP 406.
• filename — optional download filename (no extension); defaults to document_name, else document_<report_code>. Sets the Content-Disposition name.
• lod_serial — only for LOD documents.

Returns the document bytes (Content-Disposition: attachment), header X-Generator: legacy:gdwmm. Add ?meta=1 to get { status, format, bytes, source } JSON instead. Errors surface as 502 with the upstream WCF status.

Auth to the tenant WCF uses webuser-sessionid + webuser-id, configured server-side in config/template.php (legacy_wcf). The dev bypass session testtestdenning is testing-only.

12.2 Generate (native engine)

POST /v1/{server_code}/templates/generate

{ "file_no": "6000-6291", "report_code": "11199", "version_id": "1", "format": "docx" }

Provide either report_code (+version_id, resolved via the catalog) or an explicit template_path. Optional procedure, doc_type, language. Returns the document bytes (X-Tokens-Replaced / X-Tokens-Remaining headers).

12.3 Render (native, no DB)

POST /v1/{server_code}/templates/render

{ "template_path": "template/.../{guid}.bin", "merge_data": { "C1Name": "Tan Chee Jian" }, "format": "docx" }

12.4 Catalog

• GET /v1/{sc}/templates/catalog?category=&language=&kind=&mapped=yes|no&search=&limit= — list templates. Each row includes a kind: system (built-in, always present) or customized (the tenant's own). Derived from cboTemplate.location (populated ⇒ system; empty ⇒ customized) — the same split gdwmm uses. Filter with ?kind=system / ?kind=customized. Also returns report_code/version + metadata + whether a template_path is mapped.
• POST /v1/{sc}/templates/catalog — register/update an entry: { report_code, version_id?, template_path?, description?, category?, language?, doc_type?, kind? }.
• POST /v1/{sc}/templates/catalog/sync — re-seed metadata (incl. kind) from the tenant's cboTemplate.
• GET /v1/{sc}/templates/download/{report_code}?version_id=&filename= — download the source template itself (unwrapped .docx), resolved via the catalog; or GET /v1/{sc}/templates/download?template_path=.... Supports ?encoding=base64 / ?meta=1.

13. Operational Notes

• Access control is enforced for private and server files.
• Bulk endpoints may return partial; always process data.errors.
• 404 typically means missing file/path/config/job.
• 409 typically means conflict (already exists, migration in progress, active config deletion).
• 422 indicates validation errors or unsupported provider input.

Developer Onboarding - FileVault

Setup and integration checklist for engineers working with FileVault.

1. Local Setup

composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan serve

Recommended for async features (migration/jobs):

php artisan queue:work

2. Service Integration Contract

Every consuming service must provide:

• FILEVAULT_URL
• FILEVAULT_TOKEN
• FILEVAULT_SERVER_CODE

Request headers:

• Authorization: Bearer <token>
• X-User-Email: <caller-identity> (use staffCode in Denning services)

3. API Choice

Use path-based API for all new work:

• /api/v1/{server_code}/storage/*

Legacy endpoints are still present for compatibility:

• /api/v1/{server_code}/files/*
• /api/v1/{server_code}/directories/*

4. Path Design Rules

Paths must be server-code-free and follow:

• {module}/{recordId}/{sub_path}/{filename}
• documents/{sub_path}/{filename}

Do not send:

• server code in path
• leading /
• traversal segments (../)

5. Access and Identity

The metadata field on upload is optional and controls file visibility and ownership. If omitted, files default to access_level: "server" (visible to all firm users) and uploaded_by: "system".

Metadata fields:

• uploaded_by — staff code or email of uploader (default: "system")
• access_level — file visibility (default: "server"):
  • "server" — everyone in the same firm/tenant can see it
  • "private" — only the uploader can see it
  • "public" — anyone with the link

Example (restrict to uploader only):

{
  "uploaded_by": "ST0001",
  "access_level": "private"
}

Most uploads do not need metadata — just send file and path, and the file will be visible to all users in the firm.

If caller identity is missing (X-User-Email), access checks for private/server files may deny reads.

6. Tenant Storage Provider Support

Per tenant (server_code) you can:

• Save multiple provider configs (storage/configs)
• Test connectivity (storage/configs/{provider}/test)
• Activate selected provider (storage/configs/{provider}/activate)

Supported providers:

• system, s3, azure, gcp, alibaba, ftp, sftp, local

7. Storage Migration Workflow

Migration endpoints:

• GET /storage/migration/status
• GET /storage/migration/jobs
• POST /storage/migration/start
• POST /storage/migration/{migrationId}/cancel
• POST /storage/migration/{migrationId}/retry

Important:

• One active migration per tenant.
• Queue worker must be running.
• Retry only failed file IDs from previous run.

8. Reliability Patterns for Consumers

Use these rules in dp-api/dcc-api/other services:

1. Retry network and 5xx errors with exponential backoff.
2. Do not retry 4xx blindly; fix payload or permissions first.
3. For bulk operations, parse status=partial and retry only failed paths.
4. Before retrying destructive operations (move, delete), verify state with exists or list.
5. Persist file paths in your service DB so users can retry actions safely.

9. Quick Verification Checklist

• Health endpoint returns healthy.
• Upload/list/download/lookup works for your server_code.
• X-User-Email is passed from caller context.
• Path values never include server_code.
• Bulk operations handle partial responses.
• Storage config endpoints work for tenant-managed providers.
• Migration can start and report progress with queue worker active.

10. Useful Links

• API contract: docs/API_REFERENCE.md
• Integration patterns: docs/INTEGRATION_GUIDE.md
• Bruno collection: docs/bruno-collection/
• Web docs page: /integration-guide