Document Rendering Service

Access info
Endpoint https://document-rendering-api.socrate.io/graphql
Required access keys Tenant-level service access key, App-level service access key
Pricing Please contact us for details at contact@bitsoftware.ro
Notes To call the service, the access key must be provided in the x-api-key header of the HTTP request. If you are using the GraphQL console, you can view the service’s documentation and schema only after entering an access key. Make sure that the scope of the key allows access to the queries and mutations that you require. For example, to grant the key access to all queries and mutations, the keys’s scope must be set to document-rendering-api:query:* document-rendering-api:mutation:*.

Usage

The Document Rendering Service enables callers to create text or HTML templates. According to their intended usage, templates can be email or document:

  1. Email templates are useful when you need to send email with parameterized content. Specifically, the sendMessage mutation of the Email Service provides the ability to reference a template created previously through the Document Rendering Service. For such templates, you can add parameters both in the subject and body.
  2. Document templates are useful for any other contexts where you need objects with parameterized content, like HTML or text messages for your applications. Such templates do not have a subject, so you can add parameters in the body only.

According to their kind, templates can be plain text or HTML. For HTML templates, you can create separate CSS objects that you can later reference from the template. This makes it possible to apply the same CSS styles to multiple templates. If using an external CSS, you can also override the CSS style locally at the template level if needed.

Defining template parameters

To define parameters within your template, use the double curly braces syntax. For example, the following template defines two parameters, {{name}} and {{email}}:

Hello {{name}},

This is to confirm that your email address {{email}} was successfully subscribed to our newsletter.

You can execute and render the template above with a query like the one below:

query preview($input:PreviewInput) {
  preview(input:$input) {
    body
  }
}

{
  "input": {
    "template": {
      "type": "document",
      "contentType": "plain",
      "body": "Hello, {{name}}\n\n. This is to confirm that your email address {{email}} was successfully subscribed to our newsletter."
    },
    "params": "{\"name\": \"Leonardo\", \"email\": \"leo@example.org\"}"
  }
}

Notice that the value of params input variable is a stringified JSON object. The JSON object has two attributes that are both strings (name and email), each corresponding to a template variable.

It is also possible to supply objects (rather than string values) as input to the query. The code listing below has the same result, but there are two important differences:

  • The template parameters are declared as person.name and person.email
  • The input params value is a nested person object which has the name and email properties.
query preview($input:PreviewInput) {
  preview(input:$input) {
    body
  }
}

{
  "input": {
    "template": {
      "type": "document",
      "contentType": "plain",
      "body": "Hello, {{person.name}}\n\n. This is to confirm that your email address {{person.email}} was successfully subscribed to our newsletter."
    },
    "params": "{\"person\": {\"name\": \"Leonardo\", \"email\": \"test@example.org\"}}"
  }
}

Application- and tenant-level access

This service accepts both an application-level and a tenant-level security access key. The key you use determines your permissions:

  • If you have an application-level access key, you can run both the queries and mutations of this service. Any templates you create are available to all tenants of the current application.
  • If you have a tenant-level service access key, you can run only queries. This means you can check for the presence of any templates defined at application level and view their content.

Note that you can perform the actions above only if the scope of your app-level or tenant-level key features access to queries (and mutations, if applicable) of the Document Rendering Service.

Queries

css

Returns any CSS objects that match the filtering criteria.

Arguments

Argument Type Description
filter CssFilter Optional. Provides filtering options to the query.
CssFilter input
Attribute Type Description
ids [String] Optional. If this argument is provided, only CSS objects with these ids will be returned.
name String Optional. If this argument is provided, only the CSS object having this name will be returned.

Result

CssResult type
Attribute Type Description
items [Css] An array of objects of Css type.
Css type
Attribute Type Description
id String The unique identifier of the CSS object.
name String The name of the CSS object.
text String The body of the stylesheet, as a string.
author Author The details about the author of this stylesheet.
createdAt DateTime The date and time when the record was created.
updatedAt DateTime The date and time when the record was updated.
Author type
Attribute Type Description
id ID The unique identifier of the author.
name String The name of the author.
email String The author’s email address
profile String The author’s profile information.

preview

Use this query to preview a template that is not created yet (that is, apply a set of parameters to the template and view the result). Both the template values and the parameters are provided as input to the query.

Arguments

Argument Type Description
input PreviewInput Mandatory. Provides input data to the query.
PreviewInput input
Attribute Type Description
template PreviewTemplateInput Mandatory. Provides data about the template that is to be previewed.
params String Mandatory. Specifies the parameters to be applied. This must be a stringified JSON object, where each key is the parameter name, and the key’s value is the parameter value.
PreviewTemplateInput input
Attribute Type Description
type TemplateType! Mandatory. Specifies the kind of the template. Valid values: email, document.
subject String Optional, applicable only to email templates. Specifies the subject of the template.
body String! Mandatory. The body of the template that you would like to preview.
contentType contentType! Mandatory. Specifies if this is a plain text or HTML template. Valid values: plain, html.
css String Optional. Specifies any CSS rules defined locally at template level that override the external CSS (the so-called “parent” CSS).
parentCssId ID Optional. The ID of the external CSS. If provided, this must be a reference to a CSS object ID created previously.

Result

RenderingResult type
Attribute Type Description
subject String The rendered subject. Applicable only for email templates.
body String The rendered body.
contentType ContentType The template’s content type (HTML or plain text).

render

Use this query to render an existing template (that is, apply a set of parameters to the template and view the result). This query has the same outcome as the preview query, except that it accepts the template name and the template’s parameters as input.

Arguments

Argument Type Description
input RenderingInput Mandatory. Provides input data to the query.
RenderingInput input
Attribute Type Description
templateName String Mandatory. The name of the template to be rendered.
params String Mandatory. Specifies the parameters to be applied. This must be a stringified JSON object, where each key is the parameter name, and the key’s value is the parameter value.

Result

See the RenderingResult.

templates

Returns any templates that match the filtering criteria.

Arguments

Argument Type Description
filter TemplatesFilter Optional. Provides filtering options to the query.
TemplatesFilter type
Attribute Type Description
ids [String] Optional. If provided, only templates having these id’s will be included in the result.
name String Optional. If provided, only the template having this name will be included in the result.
active Boolean For future use.

Result

TemplatesResult type
Attribute Type Description
items [Template] An array of object of type Template.
Template type
Attribute Type Description
id ID The unique identifier of the template.
name String The template name.
type String The type of the template. This can be either email or document.
active Boolean For future use.
subject String The subject of the template.
body String The body of the template.
css String The local CSS rules that override the external CSS, if any.
parentCss Css The external CSS linked to this template.
contentType Css The content type of the template. This can be either plain or html.
comment String A comment associated with this template.
author Author Provides information about the template’s author.
createdAt DateTime The date and time when the record was created.
updatedAt DateTime The date and time when the record was updated.

version

Returns the API version.

Mutations

createCss

Creates a CSS object that you can subsequently reference from a template.

Arguments

Attribute Type Description
input CreateCssInput! Mandatory. Provides input data to the mutation.
CreateCssInput input
Attribute Type Description
name String! Mandatory. The name of the CSS object to be created.
text String Optional. The actual content of the stylesheet, as a string.
author AuthorInput Optional. Captures details about the author of this CSS object.
AuthorInput input
Attribute Type Description
id ID Optional. The unique identifier of the author.
name String Optional. The name of the author.
email String Optional. The author’s email address
profile String Optional. The author’s profile information.

Result

See the Css type.

createTemplate

Creates a new template.

Arguments

Attribute Type Description
input CreateTemplateInput! Mandatory. Provides input data to the mutation.
CreateTemplateInput input
Attribute Type Description
name String! Mandatory. The name of the template to be created. Template names must be unique. If a template with this name already exists, an error message will be returned in the response.
type TemplateType! Mandatory. The type of the template to be created. Valid values: email, document.
subject String Optional. The subject of the template. Applicable only for email templates.
body String! Mandatory. The body of the template.
contentType ContentType! Mandatory. The content type of the template. Valid values: html, plain.
comment String Optional. Stores comment information pertaining to the template.
author AuthorInput Optional. The template author’s details.
css String Optional, applicable only for HTML templates. Specifies any local CSS rules that override the external CSS referenced in parentCssId.
parentCssId ID Optional, applicable only for HTML templates. Specifies the ID of an external CSS object to be linked to this template.

Result

See the Template type.

deleteCss

Deletes a CSS object.

Arguments

Attribute Type Description
id ID Mandatory. The ID of the CSS object to be deleted.

Result

See the Css type.

deleteTemplate

Deletes a template.

Arguments

Attribute Type Description
id ID! Mandatory. The ID of the template to be deleted.

Result

See the Template type.

updateCss

Updates the content and author of a CSS object.

Arguments

Attribute Type Description
id ID! Mandatory. Provides input data to the mutation.
input UpdateCssInput! Mandatory. Provides input data to the mutation.
UpdateCssInput input
Attribute Type Description
text String Optional. The new content of the CSS object.
author AuthorInput Optional. The new author’s details.

Result

See the Css type.

updateTemplate

Updates an existing template.

Arguments

Attribute Type Description
id ID! Mandatory. The ID of the template to be updated.
input UpdateTemplateInput! Mandatory. Provides input data to the mutation.
UpdateTemplateInput input
Attribute Type Description
name String Optional. The new name of the template.
active Boolean Optional. For future use.
subject String Optional. The new subject of the template.
body String Mandatory. The new body of the template.
contentType ContentType! Mandatory. The new content type of the template. Valid values: html, plain.
comment String Optional. The comment pertaining to the template.
author AuthorInput Optional. The template author’s details.
css String Optional. The local CSS rules applicable to this template. If provided, they will override the external CSS defined in parentCssId.
parentCssId ID Optional. The external CSS object linked to this template.

Result

See the Template type.

Read more

Document Log Service Email Service