In this post I’ll walk through some more advanced features of Actions. The use case is with the Dexcom API, which allows for pulling data related to Dexcom’s glucose-monitoring service.
The Dexcom API requires OAuth2 authorization. In short, OAuth2 is a protocol that allows a user to grant limited access to their resources on one site (i.e. Dexcom), to another site (i.e. Rivery), without having to expose their credentials. This is becoming a more and more common means for REST APIs to allow authentication to their resources.
For this specific use case, Rivery will pull Estimated Glucose Values (EGV) from Dexcom’s EGV endpoint into a Snowflake table.
In order to comply with Dexcom’s authentication process, the following needs to happen:
- Initiate the OAuth2 handshake between Dexcom and Rivery to obtain the first access_token
- Call the authentication endpoint to generate a new access token (for subsequent pulls) as these expire after 2 hours.
- Use the newly generated access token to call the the EGV endpoint
- Load response data from the EGV endpoint into a Snowflake table
(For a more introductory walkthrough of Actions, see Actions Series Part 1).
Initiating the OAuth2 Connection
Rivery offers a built-in OAuth2 form submission in its Custom REST connector. To create a custom connection, navigate to Connections > New Connection > REST API Source.
The requirements for the OAuth2 submission are as follows:
- Auth URL
- Access token URL
- Client ID
- Client Secret
These values can usually be found in the corresponding service’s developer docs. In addition, optionally enter and additional parameters, such as allowable scopes or the specific grant type the service’s OAuth2 initiation requires.
Once the form has been filled out and submitted, a pop-up initiating the login to the desired service/API should appear and prompt for credentials. Once the credentials have been entered, the OAuth2 ‘Access Token URL’ will return a value for the first valid access token and Rivery will store this in the custom connection parameters. Check out our docs for more information on configuring a custom connection.
Call the Authentication Endpoint to Generate New Tokens
For the Dexcom API specifically, the initial authentication call returns both a valid access_token and a refresh_token to use to generate the next access_token (for when the previous one expires). In the Dexcom API, an access token is only valid for 2 hours.
Thus, the first river to create in this workflow is an Action to call the Dexcom authentication endpoint.
In the Action river Action Steps interface, set the connection to be the custom connection from earlier, and fill out the remainder of the parameters to mimic the endpoint requirements:
Note - the values in curly brackets indicate variables defined in the custom connection.
In the Results section of the Action Steps, set the type to be Variable. This is so that the variables chosen to return can then be passed into another endpoint using a Multi-Action river, which will be discussed in a later step.
In the Variable to Return section, click ‘+Add’ and enter a variable name for the access_token that will be returned in the response. For the second input, enter the key in the response that indicates the value of the new access token.
For this particular Dexcom endpoint, the key in the response data is ‘access_token’ and the variable will be named ‘new_access_token’ (variable name is up to the user).
At this point, save the river. It will be used later on as part of the Multi-Action workflow.
Use the Access Token to Perform a GET Call
This step requires an additional Action river to act as the template for the GET call to Dexcom’s EGV endpoint.
In the Action Steps set the connection and enter the correct parameter values according to the Dexcom docs.
Note that the ‘Authorization’ header contains a variable reference (indicated by the curly brackets).
To create a variable in this river, click the ‘Variables’ menu in the top right corner and enter a new variable name, such as ‘access_token’. Click ‘Add Variable’. This will act as a placeholder to the access token value to be passed from the first river created in the previous steps.
In the Results section, set the Results Type to ‘Data’. This is because this Action is meant to act as the template used to pull data into the data warehouse.
In the Data Location window, ‘egvs’ denotes the location of response data desired to be retrieved. From checking the Dexcom docs for the expected response, the ‘egvs’ key is the desired data for this use case.
Save the river, as it will also be used in the Multi-Action process.
Create a Multi-Action River to Pass Values Between Endpoints
Open up a new Action River and select ‘Multi-Action’ in the Action Steps.
In the Action Steps, set the first step to be the first action created to refresh the access_token. Here is it called ‘Dexcom - Refresh Token’.
Once the Action is selected, any accompanying input or output variables will show in the corresponding windows.
Next, add a second Action Step, and choose the Action most recently created to call the Dexcom EGV endpoint.
Notice that the {access_token} variable created in the Action shows up in the Input Variable list.
To connect the two Action Steps in the Multi-Action river, enter the output variable of the first step to be the input variable of the second step:
Notice that after typing an open curly bracket, the available variables will appear for selection.
At this point, test the Multi-Action to ensure that it runs successfully and then save. This will be used as the source template for the final river, a Data Source to Target river that will load data into a Snowflake table.
Use a Multi-Action River as a Source to Get Data Into a Target
In this final step, create a new Data Source to Target river. The source of this river will be ‘REST API Source’.
In the Source tab, choose the Multi-Action river just created in the previous step.
This means that every time the Data Source to Target river is executed, both steps of the Multi-Action will run, so that a fresh token is created and passed into the GET call of the Dexcom EGV endpoint.
In the Target step, set the destination of the data.
In the Column Mapping click ‘Auto Mapping’ so that the schema of the output table is automatically set.
At this point, the river is ready to run!
In conclusion, this article walked through the created of four separate rivers:
- Action river to refresh token
- Action river to GET data from an endpoint
- Multi-Action river to connect #1 and #2 by passing the token generated in #1 to the header value in #2
- Data Source to Target river that uses #3 as a source template, ensuring that each time the river is run, a fresh token is generated for the GET call.
Be on the lookout for Part 3 of the series, which will dive deeper into the dynamic capabilities of Actions and Multi-Actions.