Skip to main content
System StatusContact Support
VersionOne Community

Canvas API Introduction

This feature is available in Ultimate edition only.

editions-u.png

Overview

The Canvas API is a web server and REST API capable of serving Layout and Widget resources, as well as static content such as images and files.

Organization

All Canvas Resources are stored in a fixed hierarchical model. All resources have a:

  • Project - a high level grouping. All resources supporting a specific initiative should share the same Project

  • Component - with a Project, resources can be grouped into Components. Components represent refined breakdown of resources. One common Component is "shared" - for resources that may be shared by multiple other resources.

  • Name - a descriptive name of the resource.

Organizational identifiers may not contain spaces or special characters. Limit Project, Component and Name to a pattern that would make an acceptable email address.

Canvas resources are stored in the database, and can be managed using the Canvas editor.

A resource Name often includes an extension, following the pattern of a typical file system. Other resources should be named properly, such as .html, .js, .png, .gif, etc.

Proper naming not only helps with organization - it facilitates syntax checking in the Canvas editor.

Resource Repositories

Canvas resources can be stored in two different 'repositories' - an access controlled 'filesystem' repository and a user-definable 'database' repository.

Filesystem Repository

The purpose of the 'filesystem' repository is to provide a way for Continuum and/or system administrators to include 'default' content. The elements in the filesystem repository can only be edited by an Administrator.

The file system repository is considered part of the Canvas distribution - software updates from Continuum will often include updates to the content in this repository. Plan accordingly if you intend to modify any of these resources.

Database Repository

The database repository is available to developers to build customized Canvas content. Updates from Continuum will never overwrite any definitions stored in the database repository. Furthermore, Canvas elements defined in the database take precedence over items in the file system repository.

Precedence

Any request to the Canvas API for a resource (Layout, Widget or Image) will follow a default precedence rule: the database repository is checked first, and if the resource isn't found, the filesystem repository is checked.

Precedence can be programmatically specified, allowing developers to enforce explicit rules. By providing the repository argument to a Canvas API request, the precedence order can be set:

  • file - will only check the filesystem repository
  • db - will only check the database repository
  • filethendb - will check the filesystem repository first, then the database
  • dbthenfile - (default) will check the database repository first, then the filesystem

Layouts

Layout is a collection of resources intended to be rendered in a web browser as a user-facing page.

Naming Convention - A Layout definition name must have the .layout extension. The Canvas API will not render a Layout if it doesn't have the proper extension.

The API supports both GET and POST for Layouts. When POST is used, the posted data items are available as [$variables$].

Layouts should be accessed using a standard path: /project/component/name.layout

Layouts most often include an 'html' resource as a template. Be informed that accessing the .html file directly will not process the content as a Layout. .html files accessed directly will be returned as unprocessed text. In many cases this is useful, as Canvas can serve as a traditional static web server.

Widgets

Widget is a versatile, atomic 'function' in the Canvas API. Widgets can be configured to deliver all types of content, from static files to database query results. Furthermore, Widgets can be designed to update data in many different types of datasources.

As with all Canvas resources, Widgets are stored in the Canvas database, organized by Project and Component.

Naming Convention - A Widget definition name must have the .widget extension. The Canvas API will not render a Widget if it doesn't have the proper extension.

The Canvas API is a web server and REST API. Accessing a resource with the .widget extension and the proper arguments will deliver a Widget.

The API supports both GET and POST for Widgets. When POST is used, the posted data items are available as [$variables$].

Widgets should be accessed using a standard path: /project/component/name.widget

Access Control

Canvas follows a default policy of allowed unless explicitly restricted. Canvas resources are available to anyone accessing the API, even unauthenticated users.

Authenticating

Canvas is connected to the CSK Users database, therefore any Continuum user can authenticate with Canvas. There are two authentication methods available:

  • the /login page

  • the /authenticate API endpoint

The /login page is a standard web login page. Successful authentication will redirect to the 'home' page defined by the dash_api_get_index configuration setting.

The /authenticate API endpoint will answer HTTP GET and POST requests, and requires username and password arguments.

For stronger security, /authenticate requires the password be a base64 encoded string.

Tagging

Canvas resources can be associated with one or more Tags. Tags are simply text labels. If a Canvas resource has no tags, it will be public - available to anyone. Adding a Tag to a resource enables access control - that resource will now only be available to authenticated Users who are also associated with that Tag.

Tags can be managed in the Canvas Editor, by clicking the lock icon in the Resource Browser.

See Access Control for more details about Tags. See the canvas.js library for information about checking Tags on the client.

Permissions

In Canvas, the content you develop is 100% customized, therefore the permissions model is very generic, suitable for that same level of customization.

As seen above, a Tag is used to enable access control to a specific resource. Tags are not suitable for fine grained functional permissions inside your project. That's where permissions come in.

Permissions, like Tags, are simply a text label. However, where the metaphor of a Tag is a grouping mechanism, a permission is a function definition.

Permissions are associated with Tags. So, if a User is tagged as a "Operator", a permission could be created for all Operators called submit_form. Then, in the javascript for your Layout, the getPermissions() or hasPermission() functions can be used to determine availability of features on your Layout.

Permissions can be managed in the Canvas Permissions Editor.

See the canvas.js library for information about checking Permissions on the client.

Other Features

The root '/' URL

Any Canvas resource can be accesed using the root / url and a resource path. With the exception of resources with the .layout or .widget extensions, the server will return the requested resource without any processing. This is a useful method for storing and delivering static content from the Canvas repository.

Putting the proper extension, such as .css or .js on a resource will ensure it is delivered to the client using the correct HTTP Content-Type.

The '/temp' URL

The Canvas API can serve temporary files from the /tmp directory (or whichever directory is defined in the setting dash_api_tmpdir).

This feature is useful when other applications, automation scripts or other processes might need to drop a file directly on the Canvas API server for inclusion in a report.

Canvas developers should collaborate on any use of the /temp endpoint, as the path and file being served is completely arbitrary. If dash_api_tmpdir is not set, the API will default to /tmp. Remember that /tmp is subject to OS level garbage collection, and files may be deleted at any time by the OS.

The '/plain' URL

Developers may find the '/plain' option useful, as it allows a quick review of the content of any Canvas resource, without opening the editor.

 

The /plain URL will always return the resource using the text/plain Content-Type. Resources served via the /plain URL do not support [$variable$] replacement.

 

The '/session' URL

Requesting a Layout or Widget generates a Session on the API server. This Session is held in server memory. Developers may find the '/session' option useful, as it provides a quick way to get the current Session for use in client script.

All Sessions have a name, either explicitly defined in a Layout/Widget's session property, or defaulted to the name property.

The '/session' URL requires a second segment - the name of the Session to retrieve. For example:

/session/demo.layout

Would retrieve the Session for the Layout called 'demo.layout'. If session is defined, for example as "session" : "mypages", then it could be accessed as follows:

/session/mypages

The '/session' URL returns a JSON document with Content-Type of applcation/json, suitable for use as a Javascript object.

The /session URL does not support [$variable$] replacement. The Session object is delivered as-is.

  • Was this article helpful?