Home plugins create source plugin

Create Data Source Plugin

To see a working example of a data source plugin, the Evidence postgres source plugin is a good reference.

Get started

To get started, go to the data source template repo and click to "Use This Template". Then, follow the directions in the README in that repo.

Options Specification

Evidence Datasources must provide an options export; this is used to build UI and validation to ensure an excellent UX for Evidence users.

Options can have the following fields:

title
Required

Name or Title of the option

Type:
string
type
Required

Control to show

Type: stringnumberbooleanselectfile
secret

Secret values are placed in connection.options.yaml, which is not source controlled

Type:
boolean
shown

Displays value in UI elements (e.g. for usernames, that should not be source controlled but are not 'secret'. Otherwise the field will display as ∙∙∙)

Type:
boolean
virtual

Disables saving a field, useful for credential files

Type:
boolean
references

Indicates that the field should get its value from another field if it is available, useful for credential files. Formatted as a json path

Type:
string
forceReference

If true, the input is disabled and the value can only come from a reference

Type:
boolean
fileFormat

If type is file, set how it should be parsed. It will then be available to references

Type: jsonyaml
description

Description of the option, shown as a hint in UI

Type:
string
children
Type:
Record<string|number|boolean, Options>
required

Indicates that the user must provide this option

Type:
boolean
options

Available options for select type

Type:
Array<{label: string, value:string}>
nest

Determines behavior of children

Type:
boolean
default

Default Value

Type: stringnumberboolean

Children

Many datasources have variable configuration (e.g. if ssl is enabled for postgres, then an ssl mode can be selected), and Evidence options support this workflow.

Consider this partial postgres ssl option:

ssl: {
    type: 'boolean',
    // ...
    nest: true,
    children: {
        [true]: {
            sslmode: {
                // ...
            }
        }
    }
},

ssl.children is a record of possible values to an additional set of options that are exposed then the values match. In this example, the sslmode option is only displayed when ssl is true.

The resulting type of this option is:

{ ssl: false } | { ssl: { sslmode: string } }

In cases where you want a flat object, rather than a nested object; set nest to false.

This would produce

{ ssl: false } | { ssl: true, sslmode: string }

Promoting Your Plugin

If you are building a plugin for other Evidence users, let us know in Slack and we can share it with the community.