Skip to main content

Manifest And Diagnostics

Use this page when you need to understand the transparency model behind Bulk Fill best-effort execution.

What manifest.json Is For​

manifest.json is part of the Bulk Fill product contract for completed jobs. It tells you what Doqlo produced, what was partial, what failed, what was skipped, and why.

Do not treat it as extra metadata. It is how Doqlo makes best-effort execution auditable for operators and downstream systems.

Where You Find It​

Completed jobs download a ZIP artifact that includes:

  • one produced row PDF for each success or partial row
  • manifest.json

If a job fails because it exceeded max_failed_row_percent, Doqlo does not deliver a ZIP artifact. In that case, the failed job response or failed webhook contains error.details instead of a manifest download.

Top-Level Manifest Structure​

manifest.json currently includes:

  • version
  • rows
  • timestamp
  • summary
  • warnings
  • row_results

summary reports:

  • produced_rows
  • success_rows
  • partial_rows
  • failed_rows
  • applied_overlay_count
  • skipped_overlay_count

Top-level warnings are where Doqlo reports diagnostics that affect the whole job, such as compatible PDF differences between the submitted file and the package source context.

Read Reuse .doqlo Project Files Across PDFs for the product rationale and practical examples behind these PDF-context diagnostics. If you need the basic role of the .doqlo file first, read What a .doqlo project file is.

Row-Level Results​

Each entry in row_results reports:

  • row_number
  • status
  • file_name
  • applied_overlay_count
  • skipped_overlay_count
  • warnings
  • error

Row statuses mean:

  • success: the row PDF was produced and no overlays were skipped
  • partial: the row PDF was produced, but some overlays were skipped or zero overlays were applied
  • failed: no row PDF was produced

file_name always starts with the default row_{rowNumber} prefix. When the request supplied filename_columns, Doqlo appends only usable sanitized CSV-derived segments in the selected order and reports the exact produced filename here. Empty row values and values sanitized to empty are skipped, and rows with no usable selected values fall back to row-only naming. Output formatting uses underscores only, does not preserve source hyphen formatting, caps each appended segment at 24 characters after sanitization, and caps the full filename stem at 120 characters before .pdf.

Warnings And Errors​

Manifest messages use a structured shape:

  • code
  • message
  • optional details

Warnings tell you about non-fatal issues such as skipped placements or package- to-PDF differences that did not prevent the job from completing.

That includes QR/barcode overlays that were skipped because they were empty, invalid, malformed, missing a mapped column, or targeted a page that could not exist in the submitted PDF. Those overlays are surfaced as row warnings instead of failing the whole job.

Row error explains why a row failed when no row PDF could be safely produced.

Example​

{
  "version": 2,
  "rows": 3,
  "summary": {
    "produced_rows": 2,
    "success_rows": 1,
    "partial_rows": 1,
    "failed_rows": 1,
    "applied_overlay_count": 5,
    "skipped_overlay_count": 1
  },
  "warnings": [
    {
      "code": "SOURCE_PDF_FINGERPRINT_MISMATCH",
      "message": "The submitted PDF differs from the package source context."
    }
  ],
  "row_results": [
    {
      "row_number": 1,
      "status": "success",
      "file_name": "row_1_Alice_Nguyen_INV_1001.pdf"
    },
    {
      "row_number": 2,
      "status": "partial",
      "file_name": "row_2_INV_1002.pdf",
      "skipped_overlay_count": 1
    },
    {
      "row_number": 3,
      "status": "failed",
      "file_name": null
    }
  ]
}

This example means:

  • the job completed
  • two row PDFs were produced
  • one produced row was only partial
  • one row failed completely
  • the produced row filenames kept the row prefix and added sanitized CSV-driven suffixes
  • the package still ran against a compatible-but-different PDF, and Doqlo reported that at the job level

How To Interpret Partial Success​

A completed job can still contain row failures or skipped overlays. That is expected when the job stayed within your declared threshold and Doqlo could still produce a usable archive.

QR/barcode skips are a common example of this model: a row PDF may still be produced, but the row becomes partial because the code overlay was not applied safely.

Use the manifest to decide:

  • whether the completed output is acceptable for your workflow
  • which rows need follow-up or rework
  • whether you should tighten or loosen your future threshold setting

What You Get On Threshold Failure​

When the failed-row percentage exceeds max_failed_row_percent:

  • Doqlo aborts the job immediately
  • no ZIP artifact is delivered
  • no manifest.json is delivered
  • the failed job response exposes error.details with:
    • input_row_count
    • produced_row_count
    • failed_row_count
    • failed_row_percent
    • max_failed_row_percent