Connecting Bold BI to Web data source

Bold BI dashboard designer supports connecting almost all web services that has a REST API interface.

Choose web data source

To configure the web data source, follow the below steps:

1. Click the Data Sources button in the configuration panel to add a new data connection.

2. Click CREATE NEW to launch a new connection from the connection panel.

3. Select the Web connection in the connection panel.

   

NOTE: You can also create a data source from the home page by clicking the Data Sources menu from left menu panel and Create Data Source from the data sources page.

Create web data source

After clicking the data source, the NEW DATA SOURCE configuration panel opens. Follow the below steps to create web data source:

1. Enter a name and description (optional) for the data source.

2. Enter a valid REST API endpoint in the URL text box.

3. Choose one of the Method Type from the combo box for the provided REST API. Options are GET and POST.

4. If required by the REST API, provide key value pairs in Headers. To get details about headers, refer to Query Parameters.

5. Choose a time interval for Refresh Settings using the combo box to trigger the Rest API request periodically to keep the data in sync with our dashboard.

6. Choose a Data Format from the combo box based on the response of your provided REST API. Options are JSON, CSV, and XML.

7. Choose an Authentication Type supported by the data source. Options are Basic http authentication and None. Learn more about Authentication Types.

8. Choose a Pagination Type supported by the data source from the combo box.

   

Options are None, Offset, Next Page, Next Token, and Next URL.

You can also edit the connection information set here using the Edit Connection option.

Pagination types

None

It can be used when REST API does not need to be paginated. This will return first set of records alone.

Offset

Number of records to be skipped before start paginating.

For example, let’s connect OData REST API in web data source with pagination parameters as follows:

Field Name	Values	Description
URL	https://services.odata.org/V4/Northwind/Northwind.svc/Order_Details	Rest endpoint URL
Method Type	GET	Request Type of the provided endpoint
Data Format	JSON	Data format of the response for the provided Rest API
Authentication Type	None	To connect the provided endpoint, provide proper authorization credentials
Pagination Type	Offset	Number of records to be skipped before start paginating
Max Rows	7	Number of records to be fetched
Start field name	$skip	Indicates the name of the parameter to skip the records
Start field value	2	Value for the parameter *Start field name*
Count field name	$top	Indicates the name of the parameter to fetch the number of records from the index provided
Count field value	3	Value for the parameter *Count field name*
Total Records Path	(leave as blank)	To find the total records count from the obtained response. Use '.' to specify the nested key as like `data.records.totalRecords`. Refer Sample for Total Records.
Data indicator path	value	Number of records fetched will be identified from the data. Refer to the sample for Data Indicator Path.

Sample for total records

Sample for data indicator path

Next page

Number of Pages to be fetched with specific number of records per page.

For example, let’s connect Smartsheet REST API in web data source with pagination parameters as follows:

Field Name	Values	Description
URL	https://api.smartsheet.com/2.0/workspaces	Rest endpoint URL
Method Type	GET	Request Type of the provided endpoint
Header	Authorization : Bearer {:access_token}	Authorization Headers for the endpoint
Data Format	JSON	Data format of the response for the provided Rest API
Authentication Type	None	To connect the provided endpoint, provide proper authorization credentials
Pagination Type	Next Page	Pagination pairs like page/per_page, page/pageSize, etc... will be supported under this category
Max Iterations	2	Number of Iterations to paginate.
Next page field name	page	Name of the parameter to fetch the specific page
Next page field value	1	Value for the parameter *Next page field name*
Page size field name	pageSize	Name of the parameter to denote the number of records per page.
Page size field value	2	Value for the parameter *Page size field name*
Total Pages	data.records.totalPages	Specify the path where the response has the information for `total number of pages`. Refer to the sample for Total Pages.
Data indicator path	records	Number of records fetched will be identified from this path.

Sample for total pages

Sample for data indicator path

Next token

Iterate next set of records using token.

For example, let’s connect Google AdSense REST API in web data source with pagination parameters as follows:

Field Name	Values	Description
URL	https://www.googleapis.com/adsense/v1.4/accounts/{:accountId}/adclients?maxResults=2	Rest endpoint URL
Method Type	GET	Request Type of the provided endpoint
Header	Authorization : Bearer {:access_token}	Authorization Headers for the endpoint
Data Format	JSON	Data format of the response for the provided Rest API
Authentication Type	None	To connect the provided endpoint, provide proper authorization credentials
Pagination Type	Next Token	To get the next set of records, make use of token from the response
Max Iterations	2	Number of Iterations to paginate
Next token field name	pageToken	Name of the parameter used to carry the token in the request like http://sample.com/samples?pageToken=1234. To fetch nested key, refer to the sample response
Data indicator path	nextPageToken	Specify the path of the token to fetch the next set of records

Sample response

Next URL

Iterate next set of records using url obtained from response.

For example, let’s connect GitHub REST API in web data source with pagination parameters as follows:

Field Name	Values	Description
URL	https://api.github.com/events?page=1&per_page=2	Rest endpoint URL
Method Type	GET	Request Type of the provided endpoint
Header	User-Agent : Syncfusion Dashboards	Authorization Headers for the endpoint
Data Format	JSON	Data format of the response for the provided Rest API
Authentication Type	None	To connect the provided endpoint, provide proper authorization credentials
Pagination Type	Next URL	To get the next set of records, make use of URL from the response
Max Iterations	2	Number of Iterations to paginate
Next URL path	link	Specify the path to get the next url.
Look in Header	Enable checkbox	Whether to find the provided URL path in response header or not.

NOTE: To do pagination, you must provide any one of the field values, either Total Records Path or Data Indicator Path. If both values are provided, Total Records Path will be considered.

Additional information

Refresh Settings

Period of time before next refresh call is triggered. This will automatically trigger a call for the API configured in the data source to keep the data up to date. If you do not want to sync your new data, choose ‘Never’.

Query parameters

1. If required by the Rest API, pass required values as key-value pairs in Headers.
2. For POST method type, if required, pass required values as key-value pairs in Parameter(s).
3. Use either Parameter(s) or Raw for POST request.

Authentication types

1. If your data source supports authentication directly through REST API URL, choose None under Authentication Type.
2. If your data source supports API Key/API Token authentication, pass these values under Header(s) by clicking +Add. Choose None under Authentication Type.
3. If your data source has Basic HTTP authentication, choose Basic http Authentication under Authentication Type and input the username and password.

Connecting Web API data source with API Key Authentication

API Key is one of the most commonly used authentication types for REST API. API Key will be assigned to a user by the provider at the time of user creation or when enabling the API Key authentication to access the data via REST API.

API Key can be used in following places which have listed below.

• Authorization/Custom Header (Basic or Bearer).
• Query String.
• Body Data.

Adding Authorization/Custom header for API Key

To connect REST API for adding API Key in the header, you can follow below steps to connect the API in Bold BI.

• Add header in Web API data source as below.

• You need to select the Authentication Type as None.

• Header value can be either basic or bearer based on the application that you are connecting.

• Most of the API Key authentication connect using Authorization header. You can also change the name of the header key as per your need.

Adding API Key in Query String Parameter

Query String parameter will be added within the URL, so you can access the REST API without adding any header or body.

• No additional steps may require for connecting API using Query String type of API Key authentication.
• You need to select the Authentication Type as None since its API Key added in the Query String parameter.

Adding API Key in the Body Data for Post method REST APIs

Body Data usually be added for Post method API calls. If the application designed to send the API Key over the Body Data of REST API, you can follow the below steps.

• Choose POST method in Web API data source to add Body Data and add the API Key as below with relevant property names.

• You need to select the Authentication Type as None since its API Key added as Body Data.

Preview and data import

• Click Preview & Connect to connect with the configurations set.

• The Choose Schema(s) dialog opens. The schema represents the key fields of data retrieved from Web Rest API request. This dialog displays a list of schemas in treeview and its corresponding values in grid for preview. Select required schema(s) from treeview to use in designer and click Connect.

  

• Now, the data design view page with selected table schema opens. Drag and drop the table.

• Click Save to save the data source with a relevant name.

Configuring Date Parameters

You can configure the URL of the API request with templates containing date queries. The queries will be updated with respective date values.

Syntax{{:today()}}:It is used for single calendar related method.

Or

Syntax{{:today().adddays(1)}}:It is used when more than one method is added.

For example,a dummy API is used to explain here

Now, this URL will be parsed, and templates will be matched, hence the templates will be replaced with dates accordingly. This helps you to fetch data between the start date and end date.

Functions supported in date parameters

You can configure parameters as numeric values for the following functions: AddMinutes, Addhours, AddDays, AddWeeks, AddMonths, AddYears, AddQuarters, SetDayStart, and SetMonthStart.

All the Add methods should not have parameter as 0, the SetDayStart should have a numerical value between 0 and 6, and the SetMonthStart should have a numerical value between 1 and 12.

String parameters are used in the next set of functions which are start, end, format, and SetTimeZone. Both start and end functions support four string parameters which are week, month, quarter, and year. The format function is used to change the format of date and time, and the parameter is matched with the date and time format supported in C#. A support for epoch time is also made available in the format function. The SetTimeZone is used to change the time zone of the date and the parameter is matched with TimeZoneInfo IDs present in C#.

Today function does not hold any parameters. Here for example concern we are using today()as 11/16/2018 12:17

Function Name	Type(s) Used	Description	Example(s)	Result
Today	No Parameter	Sets date and time to current date and time.	{{:today()}}	11/16/2018 12:17
AddMinutes	Numerical	Updates the date and time by changing the number of minutes.	{{:today().addminutes(10)}}	11/16/2018 12:27
AddHours	Numerical	Updates the date and time by changing the number of hours.	{{:today().addminutes.addhours(2)}}	11/16/2018 14:29
AddDays	Numerical	Updates the date and time by changing the number of days.	{{:today().adddays(2)}}	11/18/2018 12:17
AddWeeks	Numerical	Updates the date time by adding a date with the numerical parameter considered as 7 days.	{{:today().addweeks(1)}}	11/23/2018 12:17
AddMonths	Numerical	Updates date and time by adding months with numerical parameter.	{{:today().addmonths(2)}}	1/16/2018 12:17
AddYears	Numerical	Updates date and time by adding years with the numerical parameter.	{{:today().addyears(3)}}	11/16/2020 12:17
AddQuarters	Numerical	Updates date and time by adding months with a numerical parameter, where parameter value 1 means 3 months.	{{:today().adddays(10).addquarters(2)}}	5/26/2019 12:17
Start	String	Sets the date and time values to the start of the given string parameter.	{{:today.addweeks(2).start(week)}}	11/25/2018 00:00
End	String	Sets the date and time value to the end of the given string parameter.	{{:today().addmonths(4).end(year{{}})}}	12/31/2019 00:00
Format	String	Formats the date and time to the correct date format entered as string parameter.	{{:today().start(week).format(MM/dd/yyyy)}}	11/11/2018
SetTimeZone	String	Changes the time zone to the time zone entered as string parameter.	{{:today().settimezone(New Zealand Time Zone)}}	11/16/2018 19:47
SetDayStart	Numerical	Updates the date to the day of the week based on the entered numerical parameter.	{{:today().Setdaystart(1)}}	11/12/2018 12:17
SetMonthStart	Numerical	Updates the date to change the month based on the entered numerical parameter	{{:today().SetMonthStart(10)}}	10/16/2018 12:17

NOTE: Each template should mandatorily start with today function. For a template, if the format function is used, it should be the last function call.

Related links

Data Transformation

Editing a Data Connection

Dashboard Designer Walkthrough