Example using the Config parameter method

In this example, you create a REST API connection to a fictional API provider using the Config parameter. This connection method references a configuration file that calls several endpoints and maps the results into a custom database schema. You then edit the configuration file to optimize future data retrieval via the connection.

Tip: Step 4 of this example describes modifying the configuration file used in the connection. You can also use the Cognos Analytics modeling tool to make changes to objects, for example, to modify label names.

Procedure

  1. You use a configuration file, for example, my_config.json, to specify the data you want returned by the REST API service.
  2. You store the file my_config.json in a central location available to everyone in your Cognos Analytics environment.

    For more information, see Store .json files in a central location.

  3. You create a connection using the Config parameter:
    1. You follow the steps in Creating a data server connection, specifying these values:
      • In the Select a type pane, you click Progress Data Direct Autonomous REST connection.
      • In the JDBC URL field, type the following:
        jdbc:ibmcognos:autorest:config="path_to_my_config.json";ServerName=url_endpoint
        where:
        • path_to_my_config.json is the path to your configuration file, which is stored in a central location.
        • The path to your configuration file is enclosed in double quotes.
        • You determine the url_endpoint by visiting the web site of the API provider.
        • The panel_id, security key, and security token are not explicitly included in the API call. Instead, they are defined in the configuration file, which is encrypted.
        • The Driver class name field is auto-filled with this text: com.ibm.cognos.jdbc.autorest.AutoRESTDriver
      • Under Authentication method, you select Connect anonymously.
    2. You save the new connection.
  4. You examine my_config.json in a text editor and modify the file, if required:
    • You can rename the schema name and panel name to be more intuitive.
    • You may notice that multiple API calls are made when using this configuration file.
    • If you want to ignore some members or rows in a table, you can comment them out using double slashes (//).
    • For each main table object, you replace actual values with a corresponding data type.
    • You may notice nested tables within the configuration file. For example, each nested table may appear as an array, denoted by a pair of square brackets ([]), under its parent table.
    • You might want to rename an original table name. For example, you want to rename labels to cardLabels. Using the configuration file syntax, you replace the code labels with labels<cardLabels>.
    For details about how to modify a configuration file: Read the topic Modifying the relational view.
  5. You create a data module based on the connection.
    Tip: See step 5 in Example that uses a fictional API provider.
  6. In the data module, you select the Relationships view.
    The table relationships are shown graphically. These relationships were generated in Cognos Analytics from the corresponding information in the configuration file.

What to do next

You can use this data module as the data source when you create, for example, a report or dashboard.