GraphQLDataSource Component
The GraphQLDataSource component enables data items to retrieve data in JSON format from a GraphQL service. At design time, the component can be configured using the GraphQLDataSource Wizard in the Standalone and the Visual Studio Report Designer. As of now, the Web Report Designer does not feature a wizard, but the data source can be configured through the Properties Area. At run time, the GraphQLDataSource component automatically issues the GraphQL request, applies authentication tokens if needed, and retrieves the data.
The data field names for this data source are case-sensitive. It is required to use the correct data field names in expressions, otherwise no data will be shown.
To preview reports that use the GraphQLDataSource component, it is required to reference the
Telerik.Reporting.GraphQL.Client.dlllibrary or theTelerik.Reporting.GraphQLDataSourceNuGet package in your application.
Configuring the Component
GraphQL Request Configuration:
| Setting | Description |
|---|---|
| Service URL | The URL the request is sent to. Returns the data from the GraphQL service. Required if inline data string or external data file is not set. The service URL should not contain any query parameters. Query parameters can be configured in the next wizard page. |
| IgnoreResponseErrors | When set to true treats any response errors as if no data is returned from the GraphQL service. The default is false. |
| Data Selector | The JSONPath expression string which will be used to query the JSON data returned from the GraphQL service. For more information please refer to How to Use JSONPath to filter JSON data. |
| Authentication | The authentication type. Basic and 2-step (Bearer) authentication is supported. A 2-step (Bearer) authentication mode can be used for the OAuth 2.0 authorization framework. Additional information is available in the following sections. |
| Encoding | Data encoding. The default is UTF-8. |
| Query | The GraphQL query to be executed against the GraphQL service. This query should be written in the GraphQL query language and must conform to the schema defined by the GraphQL service. For more information on writing GraphQL queries, refer to the GraphQL documentation. |
| Parameters | The parameters of the HTTP request to be applied. The supported types are Query, Header, Cookie, and Inline. The inline parameters are parameters that are used to replace parameter tokens (@param1) in the URL and the GraphQL query with an expression result or static value. |
Inline Data String Configuration:
| Setting | Description |
|---|---|
| Source | The inline data string containing the data. Required if Service URL or external data file is not set. Setting both Service URL and inline data string at the same time will reduce network load during design time as no HTTP requests will be made while the report is designed. Instead, the inline data will be used for any design-time operations. The Service URL will be used only at run-time (this includes data source preview and report preview operations). |
| Data Selector | The JSONPath expression string which will be used to query the JSON data returned from the GraphQL service. For more information please refer to How to Use JSONPath to filter JSON data. |
External Data File Configuration:
| Setting | Description |
|---|---|
| Source | The external data file containing the data. The URI to the file might be relative or absolute. Required if Service URL or inline data string is not set. Setting both Service URL and external data file at the same time will reduce network load during design time as no HTTP requests will be made while the report is designed. Instead, the external data file will be used for any design-time operations. The Service URL will be used only at run-time (this includes data source preview and report preview operations). |
| Data Selector | The JSONPath expression string which will be used to query the JSON data returned from the GraphQL service. For more information please refer to How to Use JSONPath to filter JSON data. |
Basic Authentication Settings
Below are listed the available settings for Basic authentication. The authentication scheme is defined in The 'Basic' HTTP Authentication Scheme (RFC 7617). This scheme transmits credentials as username/password pairs, encoded using base64.
| Setting | Description |
|---|---|
| Username | The username used to authenticate. Required. |
| Password | The password used to authenticate. |
2-Step (Bearer) Authentication Settings
Below are listed the available settings for 2-step (Bearer) authentication. The Bearer authentication scheme is defined in The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750). Bearer tokens can be used to access OAuth 2.0-protected resources. The GraphQLDataSource component supports the following OAuth 2.0 authorization mechanisms out-of-the-box:
Authorization Code Request is not supported since it requires user interaction in a browser window, which is not applicable to all Reporting use cases.
| Setting | Description |
|---|---|
| Login URL | This URL returns the authentication token or session key that allows you to access the API. Required. |
| Username | The username used to authenticate. The username and password are needed only when the Login URL uses Basic Authentication to retrieve the authentication token/key. |
| Password | The password used to authenticate. |
| Body | The body of the login HTTP request. |
| Token Path | This is a regular expression that allows to retrieve the authentication or session key from the response received via the Login URL. For example, when the Login URL returns a JSON response containing the authentication token in the form: {"access_token":"cbm9W3MeTeVPuO5CIq_DTvG5KbzydpRQ","token_type":"bearer","expires_in":1799,"userName":"demouser",".issued":"Tue, 15 May 2018 08:42:32 GMT",".expires":"Tue, 15 May 2018 09:12:32 GMT"} the token path regular expression to retrieve the token would be: (?:"access_token":")(.?)(?:")* |
| Logout URL | This URL is called if the resource features a lockout for having too many sessions open. Refresh the report and try again after successfully logging out. |
| Logout Body | The body of the logout HTTP request. |
Cookie-Based Authentication
It is possible to leverage the 2-step Authentication mechanism above to retrieve a session cookie from the server which will authenticate subsequent requests. In this scenario first, a request will be sent to the server for authentication purposes and the response should contain the generated cookie for the authenticated user. If the cookie domain and path match the GraphQL Data Source Service URL the cookie will be sent in the following data retrieval request.
When using cookie-based authentication, consider using '()' as the value for the
Token Pathwhen configuring the 2-step authentication. This will ensure that no token is found in the login response and no token will be included in the subsequent requests.
Supported developer platforms
- .NET Framework 4.6.2 and above
- .NET 6 and above
- .NET Standard 2.0 and above