API SDKs

Go SDK

Generate report with Go

Golang SDK to generate reports through the Carbone Cloud API in few lines of codes.

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

Install

go get github.com/carboneio/carbone-sdk-go

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.

package main

import (
    "io/ioutil"
    "log"

    "github.com/carboneio/carbone-sdk-go/carbone"
)

func main() {
    csdk, err := carbone.NewCarboneSDK("YOUR-ACCESS-TOKEN")
    if err != nil {
        log.Fatal(err)
  }
  // Path to your template
  templateID := "./folder/template.odt"
  // Add your data here
    jsonData := `{"data":{},"convertTo":"pdf"}`
    reportBuffer, err := csdk.Render(templateID, jsonData)
    if err != nil {
        log.Fatal(err)
    }
    err = ioutil.WriteFile("Report.pdf", reportBuffer, 0644)
    if err != nil {
        log.Fatal(err)
    }
}

Constructor

func NewCarboneSDK(SecretAccessToken ...string) (*CSDK, error)

Function to create a new instance of CSDK (CarboneSDK). The access token can be pass as an argument to NewCarboneSDK (args[0]) or by the environment variable "CARBONE_TOKEN". To set a new environment variable, use the command:

$ export CARBONE_TOKEN=your-secret-token

Check if it is set by running:

$ printenv | grep "CARBONE_TOKEN"

Example

// Carbone access token passed as parameter
csdk, err := carbone.NewCarboneSDK("YOUR-ACCESS-TOKEN")
// Carbone access token passed as environment variable "Carbone TOKEN"
csdk, err := carbone.NewCarboneSDK()

Generate a report

func (csdk *CSDK) Render(pathOrTemplateID string, jsonData string, payload ...string) ([]byte, error)

The render function takes pathOrTemplateID the path of your local file OR a templateID, jsonData a stringified JSON, and an optional payload.

It returns the report as a []byte. Carbone engine deleted files that have not been used for a while. By using this method, if your file has been deleted, the SDK will automatically upload it again and return you the result.

When a template file path is passed as an argument, the function verifies if the template has been uploaded to render the report. If not, it calls AddTemplate to upload the template to the server and generate a new template ID. Then it calls RenderReport and GetReport to generate the report. If the path does not exist, an error is returned.

When a templateID is passed as an argument, the function renders with RenderReport then call GetReport to return the report. If the templateID does not exist, an error is returned.

Example

reportBuffer, err := csdk.Render("./templates/invoice.docx", `{"data":{"nane":"eric"},"convertTo":"pdf"}`, "OptionalPayload1234")
if err != nil {
    log.Fatal(err)
}
// create the file
err = ioutil.WriteFile("Report.pdf", reportBuffer, 0644)
if err != nil {
    log.Fatal(err)
}

Upload a template

func (csdk *CSDK) AddTemplate(templateFileName string, payload ...string) (APIResponse, error)

Add the template to the API and returns an APIResponse struct (that contains a TemplateID). You can add multiple times the same template and get different templateId thanks to the optional payload.

Example

resp, err := csdk.AddTemplate("./tests/template.test.odt")
if err != nil {
    t.Error(err)
}
if resp.Success == false {
    t.Error(resp.Error)
}
if len(resp.Data.TemplateID) <= 0 {
    t.Error(errors.New("templateId not returned from the api"))
}
fmt.Println("templateID:", resp.Data.TemplateID)

Download a template

func (csdk *CSDK) GetTemplate(templateID string) ([]byte, error)

Pass a templateID to the function and it returns the template as []byte. The templateID must exist otherwise an error is returned by the server.

    templateData, err := csdk.GetTemplate("TemplateId")
    if err != nil || len(templateData) <= 0 {
        t.Error(err)
    }
    err = ioutil.WriteFile(filename, templateData, 0644)
    if err != nil {
        t.Error(err)
    }

Delete a template

func (csdk *CSDK) DeleteTemplate(templateID string) (APIResponse, error)

Example

resp, err := csdk.DeleteTemplate(templateID)
if err != nil {
    t.Error(err)
}
if resp.Success == false {
    t.Error(resp.Error)
}

Generate a template ID

func (csdk *CSDK) GenerateTemplateID(filepath string, payload ...string) (string, error)

The Template ID is predictable and idempotent, pass the template path and it will return the templateID. You can get a different templateId thanks to the optional payload.

API Token

func (csdk *CSDK) SetAccessToken(newToken string)

It sets the Carbone access token.

Carbone API version

Get

func (csdk *CSDK) SetAPIVersion(version int)

It sets the the Carbone version requested. By default, it is calling the version 2 of Carbone.

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

Set

func (csdk *CSDK) GetAPIVersion() (int, error)

It returns the Carbone version.