API SDKs

NodeJS SDK

Generate report with NodeJS

Node SDK to generates reports through the Carbone Cloud API in few lines of codes.

The source code is available on Github: https://github.com/carboneio/carbone-sdk-node

Install

$ npm i --save carbone-sdk
// OR
$ yarn add carbone-sdk

To use it, you will need your API key you can find on Carbone Account in the API access menu.

Once you have your API key, you can require the module.

const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')

INFO: Each request executed in the SDK is retry once if the first reponse request is a ECONNRESET error

Quickstart

Try the following code to generate a report in few seconds. Insert an API key, provide the template, and the data as a stringified JSON, that's it.

const carboneSDK = require('carbone-sdk')('YOUR-API-KEY');

const data = {
  data: {
    // Add your data here
  },
  convertTo: 'pdf'
}

// Create a write stream with the report name as parameter.
const writeStream = fs.createWriteStream(path.join(__dirname, 'report.odt'))
// Pass the template path as first parameter, in this example 'test.odt' is the template.
// Pass the data object as second parameter.
const carboneStream = carboneSDK.render(path.join(__dirname, 'test', 'datasets', 'test.odt'), data)

carboneStream.on('error', (err) => {
  console.error(err)
})

writeStream.on('close', () => {
  console.log('File rendered')
})

carboneStream.pipe(writeStream)

Carbone API version

You can set the version of Carbone you want to use. With this, you can upgrade your carbone version when you are ready.

To set the version, call this function:

carbone.setApiVersion(4) // Set the version of carbone to 4

Note: You can only set the major version of carbone.

Use NodeJS SDK with Carbone on premise

To set url of you local Carbone deployement :

carboneSDK.setOptions({
  // Edit the default Carbone URL (https://api.carbone.io/) for On-Premise
  // WARNING: Add a trailing slash to the end of your URL
  carboneUrl: 'https://your-on-premise-carbone-url:4000/'
})

Generate a report

There are multiple ways to render a template.

The first way is to use the templateId.

const dataToRender = {}

carbone.render('templateId', dataToRender, (err, buffer, filename) => {

})

Or if you don't want the buffer but just the link to download it later, you can set the conf like this.

carbone.setOptions({
  isReturningBuffer: false
})

carbone.render('templateId', dataToRender, (err, downloadLink, filename) => {

})

The second way is to use the path of your local file. Using this method is the most safety way to avoid errors. By using this method, if your file has been deleted, the SDK will automatically upload it again and return you the result.

const dataToRender = {}

// callback version
carbone.render('/absolute/path/to/your/file', dataToRender, (err, buffer, filename) => {

})

// promise version
const dataToRender = {}

carbone.renderPromise('/absolute/path/to/your/file', dataToRender)
  .then(result => {
    // result.content contains the rendered file
    // result.filename containes the rendered filename
  })
  .catch(err => {

})

WARNING: If you want to set a sha-256 salt to template id generation:

const dataToRender = {
  payload: 'optional-sha-256-salt'
}

carbone.render('/absolute/path/to/your/file', dataToRender, (err, buffer, filename) => {

})

You can also render you template and get result with a stream.

const dataToRender = {}

const writeStream = fs.createWriteStream('result.pdf')
const sdkStream = carbone.render('/absolute/path/to/your/file', dataToRender)

sdkStream.on('error', (err) => {

})

writeStream.on('close', () => {
  // Here you can get the real filename
  let filename = carbone.getFilename(sdkStream)
})

sdkStream.pipe(writeStream)

Upload a template

The file path must be absolute.

// callback version
carbone.addTemplate('/absolute/path/to/your/file', (err, templateId) => {

})

You can add multiple times the same template and get different templateId adding "salt" in the sha256.

// callback version
carbone.addTemplate('/absolute/path/to/your/file', 'optional-sha-256-salt', (err, templateId) => {

})

// promise version
carbone.addTemplatePromise('/absolute/path/to/your/file', 'optional-sha-256-salt')
  .then(templateId => {

  })
  .catch(err => {

})

Download a template

// callback version
carbone.getTemplate('templateId', (err, content) => {
  // content returned is a buffer
})

// promise version
carbone.getTemplatePromise('templateId')
  .then(content => {
    // content returned is a buffer
  })
  .catch(err => {

})

You can also get a template with stream.

const writeStream = fs.createWriteStream('tmp.odt')
const carboneStream = carbone.getTemplate('templateId')

carboneStream.on('error', (err) => {

})

writeStream.on('close', () => {
  // Get the real filename here
  let filename = carbone.getFilename(carboneStream)
})

carboneStream.pipe(writeStream)

The only way to get the filename when using stream is to wait the end of the request execution.

Delete a template

// callback version
carbone.delTemplate('templateId', (err) => {

})

// promise version
carbone.delTemplatePromise('templateId')
.then(templateId => {

})
.catch(err => {

})