How to rapidly build data and workflow apps with Cognite Data Fusion and Retool [Cognite Official]

The steps in this post assume that you have access to an instance of Retool and Cognite Data Fusion. It also assumes basic knowledge of Cognite resource types like Assets and Events.

A thing that customers of Cognite have realized is that it’s incredibly hard to predict today, which business processes and use cases you need to solve in the future, or even tomorrow (literally). Thus, one of the philosophies behind Cognite Data Fusion, is to enable a solid and flexible data foundation that makes building solutions and processes for new problems faster, and more scalable.

One way of speeding up the building of new apps and workflows, is to make data readily available in open, well defined and performant APIs. This lets builders use a wide range of tools, and select the best tool for the task at hand.
Here we’ll show how to build a simple mobile-friendly application with Retool and Cognite Data Fusion, to manually log production downtime events, and attach them to an Asset in Cognite Data Fusion -- in less than 1 hour 🚀.

Downtime tracking app

One of the first steps towards improving your assets’ availability, is knowing what are the most common types of downtime, and which assets cause this downtime. Some systems may be able to track this, but in many cases the information is manually recorded by personnel in the field.

To enable a production worker to enter this information in a way that can later be used for analysis, we need an app that facilitates roughly the following steps

• Search for, and select an asset from Cognite Data Fusion

• Select a category of downtime to log

• Enable a free text description field (that can later can be interpreted by ChatGPT 😜)

• Submit the event to Cognite Data Fusion, attaching it to the selected asset in the knowledge graph

But first, we need to set up a connection between Retool and Cognite Data Fusion.

Connecting to Cognite Data Fusion

As Cognite’s API adheres to the OpenAPI v3 standard, and the specification is openly available, we can use the Retool OpenAPI resource (Retool’s name for a connector). This makes all the Cognite API endpoints available from a dropdown in the connector, and also creates simple forms to dynamically populate the API parameters and payloads.

• First, create a new resource, and select the OpenAPI resource

• Give it a name

• Fill in the specification URL. It can be found in Cognite’s API documentation by right-clicking the “Download” button in the documentation and copying the link address.

Specification URL: https://storage.googleapis.com/cognitedata-api-docs/dist/v1.json

Authenticating

Retool supports OAuth authentication. We recommend using the Authorization Code grant over the client credentials grant as each user will interact with Cognite Data Fusion using their personal user account.

This will require a separate App Registration in Azure AD, as described in our documentation. Follow the guide’s step 1 to 13, and provide the following redirect URL for the web platform:

https://oauth.retool.com/oauth/user/oauthcallback

Take note of, and securely store the following elements from Azure AD:

• Client ID and client secret

• The v2 versions of Token URL and Authorization url, available under Endpoints.

In Retool, create or edit the Resource and input the authentication details like this:

Make sure to declare the correct set of scopes. Pay special attention to the user impersonation scope which is given by the cluster (base url) where the CDF project resides.

https://<your-cognite-cluster>.cognitedata.com/user_impersonation  (use the cluster of your CDF project e.g. api, westeurope-1, …).

Also, notice the “Enable an auth verification endpoint”. Configure a request that lets Retool check if the user has access, or needs to log in.

https://<your-cognite-cluster>.cognitedata.com/api/v1/<your-cognite-project>/assets

Once these steps are complete, you should be ready to start building an app!

Building the app

In this section, we’ll describe the steps to get the first query and UI component configured. See the rest of the steps in the video :)

To start building the application, go to “Apps” and create a new app. I called mine “DowntimeApp”. Now the application editor should appear. On the right you should see all the available UI components, and on the bottom and bottom left you should see the queries and query config.

In the default query, query1, select your newly created Cognite connector as the Resource. (If the queries configuration on the bottom shows a lot of curly braces, change from the General tab, to the Response tab, and back. Retool struggles interpreting some parts of the Cognite Data Fusion OpenAPI specification for some endpoints, and switching back and forth magically takes away the issue.)

Let’s define the first query. Select the “token/inspect” endpoint from the dropdown, and click preview. If this shows a response that includes “projectUrlName”, then great success!  You might be prompted to login through Microsoft, and this requires admin privileges.

Now, Retool is talking to Cognite Data Fusion. The response from this endpoint is fairly static, so for this, we select “Run only when manually triggered”, and in the “advanced” tab, tick the “Run this query on page load” checkbox. Rename the query to something more meaningful, like “token_inspect”, save it, and run it :)

Let’s create a first UI component that shows which project you’re signed in to! From the right panel, select the “Text” widget, and pull it onto the main window. While the component is selected, you see the component config on the right. 

Right away, we learn a few things:

• Each component has a name, in this case “text1”. This is how we can refer to the component from other places in Retool.

• Each component has a set of parameters and attributes, the above screenshot shows the “Value” field.

• The fields can either be manually filled in, or dynamically get content from other Retool objects. For dynamic content, the logic is written inside double curly brackets. (This logic is actually JavaScript).

To make the text box show the project info from the token_inspect query we defined before, clear the “Value” field, and instead insert the following

You're signed in to **{{token_inspect.data.projects['0'].projectUrlName}}**!

The Text widget should now show which Cognite Data Fusion project you’re signed in to!

Watch this recording to see the rest of the steps to build the downtime tracking app:
 

Thanks to @Arild Eide and @Everton Colling for helping with this post!