BigID API/Add Data Source Tutorial
- How to list available data source connectors within a system
- Where to find parameters required for a given data source
- How to test a connection to a data source
- How to add a data source using the BigID API
In this tutorial, we'll use SAMPLE as our session token. This is unique to the training sandbox and will not work in other environments. See BigID API/Tutorial for information on authenticating with BigID.
Discovering Data Sources
You can see what data source connectors are installed in your environment through the BigID UI, but since we're focused on the API (and because all actions in the UI can be performed in the API), we are going to use the API to retrieve them.
Press Send on the request below to get a listing of the data source connectors installed on our test BigID system.
You'll see our test system has around 70 different data source connectors installed. If you don't see a data source you want to use, you can develop your own or it might already exist, just not on our system. See the BigID docs for an exhaustive list.
Getting Data Source Parameters
Each type of data source has different parameters needed to connect to it. These parameters can be as simple as a username and password or as complex as rate limiting information. BigID uses templates to display these fields to the user in the UI. We can use those same templates to determine what we need to supply when adding a data source via the API. We're going to add a MySQL database. Use the below request to get the template for an rdb-mysql data source.
As you can see in the request above, there's a ton of different options to customize how we connect to a MySQL database. For our purposes, we're going to go with just the most basic options as seen below.
{
"name": "rdb-mysql",
...
"fields": [
{
"type": "string",
"name": "name",
"apiName": "name",
"displayName": "Data Source Name",
"placeholder": "Type data source name",
"mandatory": true,
"mandatoryForTest": true,
"validation": [
{
"regex": "^[\\w\\-\\s\\(\\):]+$",
"errorText": "Invalid value. Please use alphanumeric characters, spaces, underscore, dash and parentheses."
}
],
"section": "connection",
"order": 0,
"enabled": true
},
{
"type": "stringSelect",
"name": "enabled",
"apiName": "enabled",
"displayName": "Status",
"defaultValue": "yes",
"options": [
{
"value": "yes",
"label": "Enabled"
},
{
"value": "no",
"label": "Disabled"
}
],
"section": "connection",
"order": 1,
"enabled": true
},
{
"type": "string",
"name": "dbUrl",
"apiName": "rdb_url",
"displayName": "DB URL",
"placeholder": ":",
"tooltipText": "Enter a connection string to the data source.",
"section": "connection",
"mandatoryForTest": true,
"order": 0,
"enabled": true
},
{
"type": "string",
"name": "dBSchemaName",
"apiName": "rdb_name",
"displayName": "DB/Schema Name",
"placeholder": ".",
"tooltipText": "Enter database or schema name. Note: this field may be case sensitive depending on the specific data source.",
"isSeparatorAfter": true,
"mandatoryForTest": false,
"section": "connection",
"order": 1,
"enabled": true
},
{
"type": "string",
"name": "userName",
"apiName": "username",
"displayName": "User Name",
"visibleIf": [
{
"field": "useCredentialOrNamePass",
"value": false
}
],
"enabledIf": [
{
"field": "useCredentialOrNamePass",
"value": false
}
],
"mandatoryForTest": true,
"section": "connection",
"order": 6,
"enabled": true
},
{
"type": "password",
"name": "password",
"displayName": "Password",
"apiName": "password",
"visibleIf": [
{
"field": "useCredentialOrNamePass",
"value": false
}
],
"enabledIf": [
{
"field": "useCredentialOrNamePass",
"value": false
}
],
"mandatoryForTest": true,
"isSeparatorAfter": true,
"nullifyIfNotChanged": true,
"section": "connection",
"order": 7,
"enabled": true
},
{
"type": "string",
"name": "type",
"apiName": "type",
"mandatory": true,
"hidden": true,
"defaultValue": "rdb-mysql",
"section": "connection",
"order": 9,
"enabled": true
}
...
]
}
Testing a data source
In any organization, getting the correct information to access a data source can be an arduous process. Especially after data source credentials have gone through multiple levels of your organization to make it to you. Because of this, we recommend testing any data source credentials before you enter them into BigID. This will also ensure BigID has proper network connectivity to the data source. You can do this with the /ds-connection-test endpoint.
Just be sure you include 'isNewPassword' to the request, otherwise BigID will attempt to test the existing data source in your system.
Adding a data source
Now that we know what parameters to pass, let's create our data source. We just need to send a POST to the /ds_conenctions endpoint with our parameters. Let's connect to the BigID test data set:
- Type: rdb-mysql
- URL: sql.mybigid.com
- Username: bigid
- Password: bigid111
- rdb_name: rockstream
Every data source in BigID also needs a unique name. For your data source, you should use the name RANDOMHERE so you don't conflict with other users.
If we retrieve our data sources, now we should see a new data source with the information we supplied above. Use CTRL+F (or CMD+F) in your browser to find the data source you created in the request below.