Connect a data source (API)

Give Reporter a database to read, and confirm that Reporter reaches the tables that your templates use.

Participants

Your institution. Your system that calls the Reporter API.
Reporter. Stores the data source, tests the connection and reads the structure of your database.
Your database. The PostgreSQL or MongoDB database that holds the data for your reports.

#	From	To	Message	Lerian API	What happens
1	Your institution	Reporter	Lerian API	`GET /v1/data-sources`	List the data sources that Reporter knows.
2	Reporter	Your institution	Response		Reporter returns a page of data sources. The page can also show read-only data sources that the platform provides for your Lerian product databases.
3	Your institution	Reporter	Lerian API	`POST /v1/data-sources`	Send `configName`, `type`, `host`, `port`, `databaseName`, `username` and `password`. Add `sslMode` to choose the TLS mode.
4	Reporter	Your institution	Response		Reporter returns the data source with its `id`. The response does not show the password.
5	Your institution	Reporter	Lerian API	`POST /v1/data-sources/{dataSourceId}/test-connection`	Ask Reporter to test the connection.
6	Reporter	Your database	Connection		Reporter opens a short connection to your database and checks that the database answers.
7	Reporter	Your institution	Response		Reporter returns `status` `connected` or `failed`, a message and `latencyMs`.
8	Your institution	Reporter	Lerian API	`GET /v1/data-sources/{dataSourceId}/schema`	Ask for the tables and fields of the data source.
9	Reporter	Your database	Connection		Reporter reads the tables or collections and their fields.
10	Reporter	Your institution	Response		Reporter returns each table with its fields and their types. Use these names in your templates and filters.

The configName is the name that your templates and filters use. It has 1 to 100 letters, digits, underscores or hyphens. It is unique among your data sources.
When you send neither sslMode nor sslCaBase64, Reporter uses require.
When you change host, port, username, databaseName, type, sslMode, options or sslCaBase64, send the password again.
Reporter refuses to change, delete or test a read-only platform data source. You can read its schema.

The connection test returns connected, and the schema lists the tables and fields that your templates read.

Situation	What you see	What to do
The `configName` is in use or reserved	`409` or `400`, with a code and a message	Choose another name.
A field breaks a rule	`400` with `RPT-0017` and a message that names the field	Correct the field and send the request again.
The test fails	`200` with `status` `failed` and a message	Check the network path, the TLS settings and the credentials. Then test again.