Managing Canvas Datasources

Last updated
Save as PDF

Overview

Datasources are definitions that tell a Canvas Widget how to connect to a data source. Canvas can access many data sources, including: MySql, Oracle and MongoDB.

External data sources can be defined in several different ways:

as a Canvas resource
explicitly in a Widget definition.

A Datasource definition, like a Layout or a Widget, is a JSON document. Here's a straightforward Datasource definition:

{
    "type": "sql",
    "provider" : "mysql",
    "server" : "localhost",
    "port" : "3306",
    "uid" : "xxx",
    "pwd" : "xxx",
    "db" : "your_db"
}

Required Properties

type

sql - a typical RDBMS data source, accessible using SQL, such as MySql or Oracle.
nosql - a 'No Sql' data source, such as MongoDB.
http - an HTTP server, web service or API. (See below for additional http details.)

server

A hostname or IP address of the data server.

Server should not include any path information.

Optional Properties

Some optional properties are actually required based on type.

provider

Varies based on type. If type is:

sql - valid values are mysql, oracle, sqlserver, sybase, and sqlanywhere
nosql - valid values are mongo

uid

A user id, login, or other credential needed to authenticate with the data source.

pwd

The necessary password required to authenticate with the data source.

The name of the 'database' to be accessed.

port

A TCP/IP port for the data service. If omitted, provider defaults are assumed.

HTTP Datasources

The http Datasource accepts additional data defined on the Widget Options.

Yes, additional properties are stored on the Widget Options, not on the Datasource. The Datasource defines credentials and addressing, the Widget Options define interaction details.

args

The Widget Option args will be passed to the HTTP server as arguments. args must be an object:

{
    "name": "Bob"
}

method

The Widget Option method can be either get or post. (get is used if omitted.)

headers

The Widget Option headers is a dictionary of key/value headers to be sent with the request.

Regarding the Content-Type header... the Widget is making an HTTP call, but the widget itself is likely also an HTTP transatcion. The headers option for the http datasource type is different than the content_type options that determines the Content-Type of the Widget response!

path

The server property of a Datasource does not include path information, but often a datasource needs to be defined with an additional path. The path Widget Option will be appended after the server:port to form a complete URL for `http datasources.

auth_mode

A Datasource might have credential information, but the Widget does not presume to use credentials just because they exist.

If an http Widget needs to authenticate, HTTP Basic Authentication is supported, in either Direct (pre-emptive) or Challenge/Response modes.

The Widget Option auth_mode can be either direct or challenge.

direct - the Widget will send an authorization to the target server in the initial request.
challenge - the Widget will not send an authorization unless the target server challeges for it with a 401 response.

If auth_mode is omitted, no authentication attempt will be made.

Credentials

There are three ways to build a Datasource definition and include credentials.

Explicit Credentials

Explicit credentials can be defined directly on a Datasource.

While explicit credentials are useful for testing, there is no security to protect ids and passwords saved in a Datasource.

Shared Credential

A Shared Credential can be used to identify some of the properties of a Datasource, specifically the User ID and Password. Other properties must be defined explicitly.

Shared Credentials are secure - passwords are stored encrypted in the database, are never seen in an editor or transferred to a client.

Here's a Datasource definition that references a Shared Credential:

{
    "type": "sql",
    "provider" : "mysql",
    "server" : "localhost",
    "port" : "3306",
    "db" : "cato",
    "_CATO_CREDENTIAL" : "foo"
 }

This assumes a Shared Credential with the name 'foo' exists.

See the Shared Credentials for more details.

Asset

An Asset is a record of any network accessible software system, including databases. An Asset will contain all of the connectivity and authentication properties needed for a Canvas Datasource.

Assets are secure, and actually mask all sensitive properties of a data source from view. Even Canvas developer can't see the properties of an Asset..

To use the properties of an Asset in a Datasource:

{
    "type": "sql",
    "provider" : "mysql",
    "asset" : "LocalMySql"
 }

This assumes an Asset is defined with the name 'LocalMySql'.

Take note - not all Assets are usable by Canvas. Assets can be defined for many types of access - ssh, telnet, etc. Only Assets running a service accessible by Canvas can be used in a Datasource.

See the Assets for more details.