Quick Start

Full CDOGS API documentation

A demo app with sample templates is available here.

A quick example

To create a document from a template, call POST /template/render with your data, options and template as a JSON body:

{
  "data": {
    "firstName": "Jane",
    "lastName": "Smith",
  },
  "options": {
    "reportName": "{d.firstName}-{d.lastName}.txt",
    "overwrite": "true"
  },
  "template": {
    "fileType": "txt",
    "encodingType": "base64",
    "content": "SGVsbG8ge2QuZmlyc3ROYW1lfSB7ZC5sYXN0TmFtZX0hCg=="
  }
}

Template content (unencoded):

Hello {d.firstName} {d.lastName}!

Note: the template must be encoded as either a base64, binary, or hex string.

Result:

Hello Jane Smith!

Authentication

All CDOGS API calls require a valid JWT via the Authorization header (i.e. Authorization: Bearer {JWT}).

JWTs can be be obtained by passing your client credentials to the Keycloak server you've setup CDOGS with, specifically to the token endpoint. They expire after 5 minutes.

For our hosted service, the token endpoint is https://loginproxy.gov.bc.ca/auth/realms/comsvcauth/protocol/openid-connect/token.

See here for an example with authentication.

Pre-uploading templates

Frequently-used templates can be uploaded ahead of time. This avoids the need to include a copy of the template with every single document request.

To upload templates, call POST /template with the template as a base64, binary, or hex string.

The response header will contain a X-Template-Hash SHA256 hash; this is the UUID that identifies the uploaded template.

To use that template, call POST /template/{uuid}/render with your data and options as a JSON body.

An additional property, formatters, is available if you want to dynamically manipulate your data:

{
  "data": {
    "firstName": "Jane",
    "lastName": "Smith",
  },
  "formatters": {
    "{\"myFormatter\":\"_function_myFormatter|function(data) { return data.slice(1); }\",\"myOtherFormatter\":\"_function_myOtherFormatter|function(data) {return data.slice(2);}\"}"
  },
  "options": {
    "reportName": "{d.firstName}-{d.lastName}.txt",
    "overwrite": "true"
  }
}

formatters is a serialized list of functions to apply to the data. See TeleJSON for more details on serialization.

For more details on formatters, see the Carbone documentation on formatters.

Note: the hosted service has limitations on how long it stores pre-uploaded templates.

Creating templates

CDOGS uses the community version of Carbone to generate documents from templates.

Please see the Carbone documentation for help on building templates. Enterprise features (marked with a ⭐️) are not available in CDOGS.