GraphQL

For Open Source Edition, an administrator must generate an API Key before this data source can be used. See Administer API Key for instructions.

Follow the steps below to create a connection:

Watch Video: Connecting to a Database

This video might show an earlier version of the feature or operation that differs in minor ways from the current version.

  1. In the User Portal, press the top ‘Create’ button creation in the Portal, and select ‘Data Source’ database plus.

    uploadDriver2

    This opens the data source listing. To locate a data source, select the data source category in the left panel, or enter the data source name in the search field.

    datasourceList1

    If you see the ‘Create Visualization’ dialog box instead of the User Portal, press Connect to Data Source to display the data source listing.

    200

  2. Select the ‘GraphQL’ data source, and press Create. This opens the data source definition screen.

    dataSourceGraphQL1

  3. In the ‘Name’ field, enter a label for this data source connection.

  4. Enter the ‘URL’ for the web service.

  5. Select an ‘Authentication’ method (if desired). The options are ‘Basic’, ‘Two-step Token’, and ‘Oauth 2.0’.

    Basic

    If you select ‘Basic’, simply enter a username and password.

    Two-step Token

    If you select ‘Two-step Token’, specify the required information for obtaining a token (step one) and requesting data using the token (step two). Follow the steps below:

    1. Enter a username and password.

    2. Enter the ‘Authentication URI’.

    3. Press the Add button below the ‘Authentication HTTP Parameters’ label to add parameter names and values. From the menu on the right side specify ‘Header’ or ‘Query’ to indicate where the parameters should be attached.

    4. In the ‘Auth HTTP Method’, select either ‘GET’ or ‘POST’ for the first-step query. If you select ‘POST’, select a value from the ‘Content Type’ menu (application/json, application/xml, application/x-www-form-urlencoded, text/plain, text/xml), and enter the ‘Request Body’. For example:

      {
      "username": "admin",
      "password": "admin"
      }
    5. Enter the ‘Token Regex Pattern’. The regex you enter should extract the token from the response of this query. For example: "token":"(.*?)".

    Oauth 2.0

    If you select ‘Oauth 2.0’, follow the steps below:

    1. Enter the ‘Client ID’ and ‘Client Secret’, ‘Authorization URI’, ‘Token URI’, and ‘Scope’. For more details about these settings, see the Oauth 2.0 Framework Documentation.

    2. Optional: Enter one or both of the following values (space separated) in the ‘Oauth Flags’ field. Use flag credentialsInTokenRequestBody to put the ‘Client ID’ and ‘Client Secret’ credentials in the body of the request to the ‘Token URI’ when the authorization code is swapped for the access token value. Use flag useAuthorizationCodeForRefresh to indicate that the data source doesn’t provide the typical refresh token when swapping the authorization code for the access token or refresh token, and to use the authorization code again in place of a refresh token after the token expires.

    3. Press Authorize to populate the ‘Access Token’ and ‘Refresh Token’ fields.

  6. Optional: Under the ‘Query HTTP Parameters’ field, press the Add button to add the retrieved token into a parameter for the second-step query, as illustrated below (for generic REST data source). You can use the predefined {{token}} variable to represent the retrieved token value in the query.

  7. Optional: For a multi-tenant environment (Enterprise Edition only), assign any desired additional connections. See Add an Additional Connection for more information.

  8. Press OK.

    You may see the ‘Create Visualization’ dialog box at this step.

    200

    Press the ‘Close’ button close to continue with the steps below (recommended), or choose one of the following options:

    Create a Query

    Define a query based on the selected data source. See New Data Worksheet Dialog Box in Create a Data Worksheet for further instructions.

    Start from Scratch

    Open a blank Data Worksheet to build data blocks from fields of the selected data source. See Create Data Blocks in Create a Data Worksheet for further instructions.

  9. Verify that the data source you added is shown with a “check” icon submit, indicating that the connection was successful.

    dataSourceGraphQL2

    If the database is shown with an ‘Error’ icon alert circle, this means that the connection was not successful.

    dataSourceGraphQL3

    In this case, check the settings to make sure they are correct for your database. See Edit a Connection for information on how to change connection settings.

After you have created a connection to the database, you can proceed to define a data set. See GraphQL Query.