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.