Carbone v5.0.0-beta.0

Page updated on October 29, 2024.
Estimated final release date: February 28, 2025.

What's new?

• Studio - Design Assistant
• Studio - Template manager
• Studio - Embedded
• Document converters
  • Converter selection
  • Simplified deployement
  • On-Premise Configuration
• Optimizations
  • Document generation
  • Converter speed
• Template Engine
• CLI + Env Variables
• API Template List + Constant ID
• Roadmap
• Migration Recommendation
  • HTTP API
  • Studio
  • On-Premise middleware
  • Templates

Where to test it?

• Docker: https://hub.docker.com/r/carbone/carbone-ee/tags?name=5.0.0-beta
• Linux binary: Carbone-ee-5.0.0-beta.0-linux-x64
• Mac Binary: Carbone-ee-5.0.0-beta.0-mac-x64
• Carbone Cloud Studio: In the Studio, click on the lab icon (top-right corner), available starting October 30.
• Carbone Cloud API: Update the HTTP header to carbone-version: 5

Studio - Design Assistant

Historically, Carbone had two different "studios":

• A "stateless" version, available in Carbone On-Premise.
• A more complete version, only available in Carbone Cloud Edition, with a completely different technical stack.

We have been working for about a year to unify everything and offer the same tool for Cloud, On-Premise, and even within your application with an embedded solution.

The new studio is composed of two parts (two pages):

• Designer Assistant: This is the main part of the studio where you can test, debug, and build your templates. Now, this part can be embedded into your application (as a Web Component).
• Template Manager: This part will display the list of templates, similar to a file explorer like Google Docs or Dropbox. This part is hidden during the beta phase.

Here are all the new features of the Designer Assistant:

Studio - Template manager

This feature is hidden during the Beta phase. View our roadmap.

Studio - Embedded

Embed Carbone Studio directly in your application!

From the software editor's perspective:

• Make all reports in your app customizable.
• Increase revenue potential by upselling access to this feature or offering personalized reports.

From the user's perspective:

• Enjoy a seamless experience by editing reports directly within the application.
• Automatically open the studio with user data as a sample.
• Add documentation to explain your data (coming soon).

From the developer's perspective:

• The studio is a customizable, lightweight HTML5 web component compatible with all front-end frameworks like Vue.js, React.js, Angular, and Riot.
• The studio requires only four endpoints to function.

Important notes and consideration during the beta phase:

• Do not use it for production: This beta version is intended for testing and feedback only.
• Potential Instability: It may contain bugs or incomplete features; we plan to release regular updates.
• Breaking Changes: Future updates may include breaking changes, so be prepared for possible API changes or deprecations.

1. Load the web component file

• Start Carbone On-Premise with -s option to start the studio.
• Then, download the js from there with this URL http://localhost:4000/carbone-studio.js (More option with CDN will come soon)
• Include the JS file in your app:

  <script src="/carbone-studio.js"></script>
  <style>
    carbone-studio {
      height:100%;
      width:100%;
    }
  </style>

2. Start the studio

// Instantiate the Web component
const studio = document.createElement('carbone-studio');
// Or insert `<carbone-studio></carbone-studio>` directly in the DOM.
// Add the studio component to the DOM
document.body.appendChild(studio);             
// Configure the studio
studio.setConfig({
  origin : 'https://api.carbone.io/', // Defaults to `window.location.origin`
  token  : '',                        // Provide a JWT Token if authentication is enabled on your On-premise instance
});


const templateFile = {
  // The studio will automatically call `URL_ORIGIN/template/:templateId` to download the template
  templateId : '424242424242424242424242424',
  // Extension is used for the user interface and may change in the future
  extension  : 'docx' 
};
// Pre-initialize the studio with data, language, etc.
const options = {
  data           : {},
  complement     : {},
  enum           : {},
  translations   : {},
  lang           : 'fr-fr',         // Defaults to browser language
  timezone       : 'Europe/Paris',  // Defaults to browser language
  currencySource : 'EUR',           // Defaults to browser language
  currencyTarget : null
};
// Open the template in the studio
studio.openTemplate(templateFile, options);

URLs called by the studio:

• POST /render
• GET /render/:id
• POST /template
• GET /template/:idTemplate

More options for request hooks are coming soon; we look forward to your feedback!

3. Listen events

  studio.addEventListener('connected');
  studio.addEventListener('disconnected');
  studio.addEventListener('options:updated', optionsUpdated);
  studio.addEventListener('template:updated', templateUpdated);
  function optionsUpdated(e) {
    console.log(e.detail);
    // {
    //   "data": {}
    // }
  }
  function templateUpdated(e) {
    console.log(e.detail);
    // {
    //   "templateId": "424242424242424242424242424",
    //   "extension": "docx"
    // }
  }

Document converters

Carbone merges data with templates, but the document conversion (e.g., DOCX to PDF) has traditionally been handled by a single external tool, LibreOffice.

Even though we financially support the LibreOffice foundation every year, we have a deep knowledge of LibreOffice's technical limitations. This is why we wanted to lift this constraint and offer more flexibility.

Now, you can choose from 4 different document converters, all managed directly by Carbone.

Carbone Ice is our own converter for specific use cases where very high performance is required.
We may stop working on this solution if OnlyOffice or LibreOffice become as fast as our solution 😛.

Converter selection

• With the API:

  {
    // L : LibreOffice
    // O : OnlyOffice
    // I : Carbone Ice
    // C : Chrome
    "converter" : "L",
    "convertTo" : "pdf",
    "data"      : {}   
  }

• In the studio:

• Other methods:

  By default, LibreOffice is used. During the beta phase, we will gather feedback from you to determine the best method for selecting the converter. When the stable version of Carbone v5 is released, we may offer additional options like "automatic selection" or "fastest."

Fast Round Robin Conversion Queue

Internally, Carbone balances conversion jobs across multiple threads.

It ensures that only N (params.factories) jobs are executed in parallel, regardless of the number of converters.

This feature also introduces a new "two-level" priority system for job conversion. All tasks are guaranteed to be executed, and high-priority tasks will not starve low-priority tasks. More details will be provided later.

Simplified deployement

Carbone is compatible with the default installation of these external converters.

However, in a server environment, you likely want secure, compact software with minimal dependencies for your servers or Docker images.

That’s why we provides pre-built binaries on our own CDN (bin.carbone.io), offering optimized and compact versions of all these tools: LibreOffice, OnlyOffice, and Chrome, for multiple architectures (ARM, x64).

Several new Docker images are available as examples. You can use any of them or use our Dockerfile as a template to build your own.

On-Premise Configuration

By default, Carbone On-Premise starts with LibreOffice.

To activate the OnlyOffice converter, install OnlyOffice Desktop on your Mac or use our Debian package (Linux):

Then, configure Carbone as follows:

  factories       : 4,      // = nb CPUs
  libreOfficePath : 'auto', // = env CARBONE_EE_LIBRE_OFFICE_PATH
  onlyOfficePath  : 'auto'  // = env CARBONE_EE_ONLY_OFFICE_PATH

Other options will be documented soon.

Optimizations

One of our main development principles is to make each new version faster than the previous one. Carbone v5 marks an important milestone with documents that can be generated up to 10 times faster compared to Carbone v4.

Document generation

Opening templates and saving generated documents can account for 35% of Carbone's internal resource consumption, excluding the time spent on document conversion. We achieved a 4x improvement in template opening speed and a 2x improvement in saving the generated document. Overall, this results in a 2x performance gain on a 15MB PPTX template (without PDF conversion) between Carbone v4 and Carbone v5:

Converter speed

Carbone v5 supports multiple document converters (see the previous section above). OnlyOffice can be used as a replacement for LibreOffice, and here are our benchmarks for converting a large and complex 200-page DOCX file to PDF:

OnlyOffice may be slightly slower for small documents (due to a higher cold start compared to LibreOffice), but we will optimize this before the final release of Carbone v5.

Template Engine

All prerelease features delivered in v4 with optional flags {o.preReleaseFeatureIn=4022011} are now activated by default for all templates.

This new v5 engine is more stable and handles more complex use cases compared to v4, while maintaining backward compatibility with v4.

Here are the major improvements:

• Supports a wider range of use cases for conditional blocks and loops. It handles more scenarios and significantly reduces the likelihood of creating an invalid file ("Could not open document" error). The engine now accepts syntaxes that may not be logical for a computer but are understandable for a human, especially in documents. For example, writing tags in a document can sometimes generate an algorithm like this:

  IF
    START LOOP
      END IF
    END LOOP
    // END IF should be here for a computer. Carbone fixes this automatically

  This example below, which combines filters, aggregators, and a conditional block on the same array, was not supported without this new algorithm: Additionally, it is no longer necessary to repeat the full tag at the end of a conditional block; {d:showEnd} or {d:hideEnd} is sufficient.

  {d.arr[sort>1].id:aggCount:ifGT(0):showBegin}
    {d.arr[i].id}
    {d.arr[i+1].id}
  {d:showEnd}

• 😎 Improved syntax error detection and clearer messages when debug mode is activated (see screenshot of the studio above).

• 🥳 Enhanced support for XLSX files (e.g., no suppression of empty cells).

• Added support for bindColor in PPTX templates (for text, background color, and shapes).

• New :transform(axis, unit) formatter to move an image or shape in ODT/ODP/PPTX on the X or Y axis:

  • axis can be x or y to move the item horizontally or vertically from its current position. Positive numbers move the item to the right or bottom.
  • unit can be cm, mm, inch, or pt.

• Whitespace is now accepted in attribute names when using single quotes: {d.'new param'.'second level yes'[1].'sub obj'}. Known limitation: This is not accepted inside formatters, array filters, and aliases.

• Fix: Conditional blocks (show, hide) and smart conditional blocks (drop, keep) were not executed when combined with an array filter. In this example {d.arr[i, filter=3].id:ifEM:hideBegin} AAAA {d.arr[i, filter=3].id:hideEnd}, AAAA was printed if no rows matched the condition filter=3.

• ⚡️ Transform your JSON without limits using :set(). This formatter, introduced in v4.5.2, was previously limited. It can now be used to convert a flat JSON into a new hierarchical JSON with unlimited array depth, or vice versa (more details to come).

CLI + Env Variables

The CLI has been completely rewritten for greater clarity and ease of use when starting and deploying.

• Added new interactive tools to generate key pairs, tokens, and verify tokens.
• The Carbone CLI can now be used directly without needing to enter the Docker container. By default, it still starts the web server as before.
• A new CARBONE_AUTHENTICATION_PUBLIC_KEY environment variable allows passing the public key (in stringified PEM format) when authentication is enabled.
• Proper support for SNAKE_CASE_UPPER_CASE has been added for all environment variables. The previous format used an inconsistent partial snake_case.
  • For backward compatibility, both formats are accepted: CARBONE_EE_AUTHENTICATIONPUBLICKEY (old method) and CARBONE_AUTHENTICATION_PUBLIC_KEY (new method).
  • The new format takes precedence if both environment variables are provided.

API Template List + Constant ID

We know that many of you are waiting for:

• An API to list all templates.
• The ability to use a constant template ID.

This feature will be made public for Carbone On-Premise as soon as it is in production for the Cloud Edition in February 2025. View our roadmap. Why? Once it runs at scale on our Cloud architecture, it will work for your On-Premise environment as well.

We are working hard to keep things simple and ensure easy deployment on any architecture (Servers, OpenStack, Docker, Kubernetes, AWS, Azure, and GCP, with or without a private network).

Our promise is to maintain a single and simple Carbone binary that is just as easy to deploy on one machine or across multiple machines.

For the curious, Carbone v5 will embed an SQLite database and a NATS messaging system. Both are self-managed by Carbone. Object storage is still recommended for storing templates when deploying Carbone on multiple servers.

Roadmap

Carbone v5 will remain in beta until the end of February 2025.

Some parts are stable, while others are hidden and will be delivered later. To make things clear, here is our roadmap:

Known bugs/limitations

Missing feature or known bug compared to On-Premise v4 Studio:

• Add the option to switch between data, complement, translation, and constants
• Auto-save data after X seconds
• Improve the style of the data panel
• Remove the auto-fix/indent feature for JSON to prevent losing the folding/unfolding state every time the data is updated
• Add the ability to search within the JSON data
• Fix double extension in downloaded documents
• Windows is not supported yet

Migration Recommendation

HTTP API

• Cloud: Switching requires a manual change on your side. All API requests must include the HTTP header carbone-version: 5. Take your time: the v4 API will be available for at least another 2 to 3 years. We maintain the last three major versions.
• On-Premise: Download and install the new version

No breaking changes.

Important notes: GET /render/<idRender> now returns the correct HTTP header Content-Disposition:

Studio

• On-Premise: The new studio replaces the old one.

  • Phase 1 (Oct-24): Stateless mode with only the Designer Assistant, and the "Embeddable Mode" as a Web Component.
  • Phase 2 (Feb-25): Activatable full studio (same as cloud edition) with template manager, versioning, constant ID, and embedded SQLite database, along with a messaging system between multiple Carbone nodes.

• Cloud: The new studio is accessible only through the "Lab" button (top right corner) during the entire beta phase.
  Any edits made to the JSON or Template file will be saved in the Studio database. It will fully replace the current studio in March 2025.

On-Premise plugins

• Carbone v5 relies on NodeJS 22.
• Breaking change: Function signatures and behavior will change when the final version is released in February 2025.

Templates

We always recommend testing your templates before migrating to v5.

1. The Carbone v5 template engine is backward compatible with templates made for previous Carbone versions.
   Despite our thousands of tests, there is always a slight chance of a regression.
   Please contact us as soon as you encounter any issues.

2. The main impact often comes from the version of the converter, LibreOffice.
   If you use Carbone On-Premise, you can still use an older version of LibreOffice with Carbone v5.
   The Cloud Edition (API v5) uses the latest LibreOffice version (24.8), while Carbone Cloud v4 uses LibreOffice 7.5.
   Therefore, document conversion may vary when switching from v4 to v5 (especially for DOCX to PDF). This is an opportunity to try the alternative converter OnlyOffice, which performs almost pixel-perfect DOCX-to-PDF conversions.

   We have extensive experience solving these problems, so feel free to contact us if you need help. For example, there are two DOCX features that are not well supported by the LibreOffice converter, even in the latest version (24.8):

   • Sections
   • The "Text Wrapping -> Arround" option for tables, charts, etc. (see figure below). We have created an issue.