Managing Canvas Datasources
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 aremysql
,oracle
,sqlserver
,sybase
, andsqlanywhere
-
nosql
- valid values aremongo
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.
db
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.