Connections
Connections are a key part to how Apps work and every App must have a connection assigned to it.
A connection allows you to collect any information you might need from the user that would be required for the App to connect to the external system such as an API key or configuration parameters for their installation.
When you create your App, the first thing you will be asked for is the connection type of the app which could be one of two types.
Generic Connection Type
A generic connection type allows you to define a set of fields to collect from the user when they install your app. This could be items such as an API key or some other information that you would like the user to provide when installing this App.
For our weather App, we're going to add an API Key parameter to collect which we will use later when calling the weather API.
We can also mark any connection parameter as sensitive which will make sure it's stored securely in Flows.
Once you define a connection parameter you can reference it from any of your App flows by using <ConnectionParamKey>
oAuth Connection Type
oAuth is a standard way for users to connect two systems together in an easy and familiar way whereby the end user is taken to the 3rd party site to authorise access to Flows.
If you are not familiar with the concepts around you can learn more about it in the following links:
https://en.wikipedia.org/wiki/OAuth
https://auth0.com/intro-to-iam/what-is-oauth-2/
Flows makes it easy to setup an oAuth connection type without the need to code by allowing the settings to be configures through Private Flows. When creating a new App and setting the connection type as oAuth, 3 private flow templates are automatically created for you which you can adjust for your 3rd party service:
OAuth Step 1 - Build Authorisation URL
OAuth Step 2- Exchange temporary token for access and refresh token
OAuth Step 3 - Refresh access token
Before continuing with setting up the oAuth flows, you will need to collect the following information:
An OAuth application configured in your own app’s settings, where you’ll add the Flows OAuth Redirect URL. [Used in Step 1]
An Authorisation URL on your app’s site where users will log in with their account credentials [Used in Step 1]
A list of API scope(s) to restrict what Flows can access [Used in Step 1]
A Client ID (may be called Customer or API Key) and Client Secret (may be called Customer or API secret) from your app [Used in Step 1 & 2]
An Access Token Request URL where Flows exchanges the temporary token for an access token [Used in Step 2]
A Refresh Token Request URL (optional) where Flows can refresh the access token if it expires. [Used in Step 3]
A Test API endpoint where Flows can make an API call to ensure your user credentials work
Once you have the above information, you are ready to configure each of the three oAuth private flows.
OAuth Step 1 - Build Authorisation URL
The first step is to build the authorisation URL that Flows will use to get a temporary token from the 3rd party service.
In the first stage, enter the values for your AuthURL and the Scopes that you will need to access in the service.
In the second stage, you can enter any other optional parameters that the service may need during initialisation. If there are no optional parameters needed then you stop here however, if any parameters are added in this stage then they will also need to be added in the 3rd stage when building the URL..
The objective of step 1 is for the flow to return a single data field with key called "authorizeUrl" and a value which is the URL that the client will be redirected to when authorising Flows with the 3rd party application
OAuth Step 2 - Exchange temporary token for access and refresh token
Step 2 of the private flows will automatically take the temporary token passed in the callback from the 3rd party service and exchange it for an access token and (optional) refresh token.
In the first step (trigger) several input variables to the flow are specified. These correlate to the fields that are present in the callback URL from the 3rd party service. They typically follow the same naming convention but you may need to adjust the field names coming in the callback if they are different. Any changes made here would also need to be reflected in any references to the field later in the flow.
Following the first stages, a request will be built up to the 3rd party service using the temporary token, In the Call API block depicted above, you will need to add the correct URI Base and URI Path for the 3rd party endpoint used to exchange the temporary token for an access token. This is typically found in your 3rd party service admin panel or documentation.
Once you have configured these parameters you can save the flow. The second step is complete.
OAuth Step 3 - Refresh access token
Step 3 is an optional step that can be used from any of your App's Public or Private flows in order to refresh an access token that may have expired. Not all 3rd party services require this so you will need to see if access tokens expire in your 3rd party service and how best to refresh them. Typically a refresh token has a much longer expiry time than an access token so one possible method is to call this Flow whenever you receive an error from a 3rd party service call that indicates the access token is expired.
To configure this Flow to be used you need to simply set the URI Base and URI Path in the Call API stage above to reflect the refresh API endpoint of your 3rd party service.
Once that is complete you should be able to call it from any of your other App Flows.
NB: This flow requires you to pass to it a ConnectionID which will be available to you in any other flow through the parameter <ConnectionID>
Connection Test
When creating a new App a private flow called connection test is automatically created. This flow is a special private flow that is user to test the connection to the 3rd party service and will need to update it to properly make a connection test. Typically a connection test can be done by calling one of the more basic APIs on the external service and checking to see if a proper response is returned.
This flow can be called by the use once they install the App and sets up a connection to make sure that the App is working as expected.