Generate reports

JPG/PNG options

It is possible to export jpg or png images with options (list bellow).

Here is an example of exporting a JPG image with options:

{
  "convertTo": {
    "formatName" : "jpg",
    "formatOptions": {
      "Quality"   : 50,
      "ColorMode" : 1
    }
  }
}

CSV options

During CSV conversion, the following elements can be changed: separator, delimiters and the character set. convertTo have to be an object with formatName set to csv and formatOptions with options. characterSet can be one these options : https://wiki.openoffice.org/wiki/Documentation/DevGuide/Spreadsheets/Filter_Options

{
  convertTo : {
    formatName    : 'csv',
    formatOptions : {
      fieldSeparator : '+',
      textDelimiter  : '"',
      characterSet   : '76' // utf-8
    }
  }
}

Asynchronous jobs

When the report is huge, we highly recommend employing the asynchronous rendering system. This method offers a longer rendering timeout of 5 minutes, surpassing the 60-second limit of the synchronous API.

Carbone will notify your application/service at a custom URL as soon as the document is generated.

How to use this system?

1. Prepare your server to accept POST requests at a webhook endpoint. For experimentation, https://webhook.site/ is a convenient option.
2. Send a request to POST /render/:templateId with the HTTP header carbone-webhook-url: https://my-custom-webhook/my-custom-url
3. (From version 4.23.0) If your webhook url needs authentication or a specific header, you can configure it by adding the header carbone-webhook-header-X. Ex : carbone-webhook-header-authorization: my-secret
4. Upon report completion, Carbone will invoke your webhook endpoint, sending a JSON object that includes the renderId. The response object is the same as the response from the synchronous method.

Carbone automatically retries (one retry) to call your webhook for the following errors:

• Status Code Errors: 408, 429, 502, 503, 504, 521, 522, 524
• Socket Errors: ETIMEDOUT, ECONNRESET, EADDRINUSE, ECONNREFUSED, EPIPE, ENOTFOUND, ENETUNREACH, EAI_AGAIN
• Request Timeout (16 seconds max)

Batch processing

Starting from version 4.20.0, Carbone introduces the capability to generate multiple reports in one go using a single HTTP request, with the same template. This feature streamlines the creation of reports, especially when dealing with bulk data, by returning a compressed ZIP file that contains all generated reports.

Batch processing is particularly useful for generating personalized documents, such as letters or invoices, for multiple recipients simultaneously.

Batch processing is enabled if all of the following conditions are met

• Include the batchSplitBy attribute in the POST /render/:templateId request (see below).
• Utilize asynchronous job processing by setting the carbone-webhook-url HTTP header in your request (see above).
• Only for Cloud: Ensure the data payload contains a non-empty array with up to 100 objects (= 100 reports)
• Only for On-Premise: The global configuration parameter nbReportMaxPerBatch is greater than 0.

API Request Example

To initiate batch processing, send a JSON object structured as follows:

{
  "data"         : {
    "letters" : [
      { "id" : 1, "name" : "John"   },
      { "id" : 2, "name" : "David"  },
      { "id" : 2, "name" : "Steeve" }
    ]
  },
  // The result will be a ZIP file of multiple PDFs
  "convertTo"    : "pdf",
  // Batch processing option.
  "batchSplitBy" : "d.letters"
}

batchSplitBy determines how the batch is split. Accepted values:

• "d" if data is an array of objects, resulting in one report per object.
• "d.myCustomField" to select a direct child array of "data", resulting in one report per object in that array.

Template Writing Methods

When writing templates for batch processing, you can employ two approaches. Carbone automatically detects the method used.

1. Direct child access: Write the template directly at the d.letters[] level, using placeholders for each data field.

    {d.id} {d.name}

2. Array access: Write the template at the root level d. For each report, Carbone generates an array containing a single object, thereby producing one report for every object within d.letters.

    {d.letters[i].id}    {d.letters[i].name}
    {d.letters[i+1].id}

Download report with single API call

Add a new option to the API endpoint POST /render/:idTemplate. The query parameter ?download=true can be used to download the rendered report directly.

When this option is used, the file is not stored on our servers. A single API call is enough to download the file. There is no need to call GET /render.

Important: The Content-Disposition header changes based on the HTTP status: If the status is 200 (OK):

  Content-Disposition: 'attachment; filename="report.pdf"'
  Content-Type: 'application/pdf'

For all other statuses: The response remains in application/json format as before.