Integration guides
This page contains various Integration Guides
Last updated
This page contains various Integration Guides
Last updated
You can use various methods to establish a connection between Cinchy and Microsoft Excel, such as using Basic Auth, Personal Access Tokens, or Bearer Tokens.
Review each section below for further details.
Excel connects to queries within Cinchy, so before you use any of the connection methods below you will need to create one that represents your dataset. Once created, you will need to copy down the REST API URL endpoint, located as a green button on the right-hand side of the Execute Query screen.
The structure of the URL endpoint is <your Cinchy instance URL>/API/<the name of your query>. You might optionally have querystring parameters at the end as well.
For example: http://your.cinchy.instance.domain/API/YourQueryDomain/API Test
Note that for Basic Authentication with a result format of CSV we will use a slightly different URL endpoint.
For Basic Auth: /API/ becomes /BasicAuthAPI/
For CSV results you will add the querystring parameter of ResultFormat=CSV
Our example URL of a basic auth using CSV results would then become: http://your.cinchy.instance.domain/BasicAuthAPI/YourQueryDomain/API Test?ResultFormat=CSV
Launch Excel and navigate to Data > Get Data > From Other Sources > Blank Query (Image 1).
In the expression box that appears, enter the below text to add in your query as your data source (Image 2):
=Csv.Document(Web.Contents("API ENDPOINT URL"))
Example:
=Csv.Document(Web.Contents("http://your.cinchy.instance.domain/BasicAuthAPI/YourQueryDomain/API Test?ResultFormat=CSV"))
Once you've entered that text either click the check mark to the left of the input box or click away and it will automatically attempt to run the expression.
The data may return in HTML format initially and not be what you're expecting. To correct this:
Select the Data Source Settings.
Select Basic and enter the credentials for a Cinchy User Account that has access to run this query.
Select OK.
Within the Edit Permissions dialogue, click OK.
Within the Data Source Settings dialogue, click Close.
Select Refresh Preview.
Select Close & Load and your dataset will be displayed in the Excel worksheet.
If needed, follow the documentation here to generate a new PAT.
Launch Excel and navigate to Data > From Web.
Select Advanced and input the following values (Image 3):
URL Parts: This is the Query API URL that you created in the Prerequisites section.
HTTP Request Header Parameters:
In the first text box input Authorization
In the second text box type Bearer + your PAT. For example: "Bearer BGFHFHOJDF76DFDFD777"
Select OK.
Select Load to use the query data in Excel (Image 4).
If needed, follow the documentation here to generate a Bearer Token.
Launch Excel and navigate to Data > From Web.
Select Advanced and input the following values (Image 5):
URL Parts: This is the Query API URL that you created in the Prerequisites section.
HTTP Request Header Parameters:
In the first text box input Authorization
In the second text box type Bearer + your token. For example: "Bearer eyUzI1NiIsImtpZCI6IkE4M0UwQTFEQTY1MzE0NkZENUQxOTFDMzRDNTQ0RDJDODYyMzMzMzkiLCJ0eXAiO"
Select OK.
Select Load to use the query data in Excel (Image 6).
You can use various methods to establish a connection between Cinchy and Power BI, such as using Basic Auth, Personal Access Tokens, or Bearer Tokens.
Review each section below for further details.
Power BI connects to queries within Cinchy, so before you use any of the connection methods below you will need to create one that represents your dataset. Once created, you will need to copy down the REST API URL endpoint, located as a green button on the right-hand side of the Execute Query screen.
The structure of the URL endpoint is <your Cinchy instance URL>/API/<the name of your query>. You might optionally have querystring parameters at the end as well.
For example: http://your.cinchy.instance.domain/API/YourQueryDomain/API Test
Note that for Basic Authentication with a result format of CSV we will use a slightly different URL endpoint.
For Basic Auth: /API/ becomes /BasicAuthAPI/
For CSV results you will add the querystring parameter of ResultFormat=CSV
Our example URL of a basic auth using CSV results would then become: http://your.cinchy.instance.domain/BasicAuthAPI/YourQueryDomain/API Test?ResultFormat=CSV
Launch Power BI and navigate Get Data > Web (Image 7).
In the window that launches, you will enter the below text, using your own URL endpoint where highlighted (Image 8):
=Csv.Document(Web.Contents("http://your.cinchy.instance.domain/BasicAuthAPI/YourQueryDomain/API Test?ResultFormat=CSV"))
Click on the checkmark icon and Power BI will automatically attempt to run the expression (Image 9).
Select Edit Credentials > Basic (Image 10). Enter the credentials for a Cinchy User Account that has access to run this query and select the level at which to apply these settings. By default it's the root URL.
This process of entering your credentials won't occur with each query, it's just the first time and then they're saved locally.
Select Connect to see your data (Image 11).
You can now apply any transformations to the dataset.
In this example we also changed the name from Query1 to Product Roadmap and have edited to use the first row as a header (Image 12).
Select Close & Apply. The metadata now shows up on the right hand side and you can begin to use it to create your visualizations (Image 13).
If needed, follow the documentation here to generate a new Personal Access Token (PAT).
Launch Power BI and navigate to Get Data > Web.
Select Advanced and input the following values (Image 14):
URL Parts: This is the Query API URL that you created in the Prerequisites section.
HTTP Request Header Parameters:
In the first text box input Authorization
In the second text box type Bearer + your PAT. For example: "Bearer BGFHFHOJDF76DFDFD777"
Select OK.
Select Load to use the query data in Power BI.
You can now apply any transformations to the dataset.
In this example we also changed the name from Query1 to Product Roadmap and have edited to use the first row as a header (Image 15).
Select Close & Apply. The metadata now shows up on the right hand side and you can begin to use it to create your visualizations (Image 16).
If needed, follow the documentation here to generate a Bearer Token.
Launch Power BI and navigate to Get Data > Web.
Select Advanced and input the following values (Image 17):
URL Parts: This is the Query API URL that you created in the Prerequisites section.
HTTP Request Header Parameters:
In the first text box input Authorization
In the second text box type Bearer + your token. For example: "Bearer eyUzI1NiIsImtpZCI6IkE4M0UwQTFEQTY1MzE0NkZENUQxOTFDMzRDNTQ0RDJDODYyMzMzMzkiLCJ0eXAiO"
Select OK.
Select Load to use the query data in Power BI.
Cinchy exposes a Tableau Web Data Connector that provides access to Cinchy Saved Queries as data sources in Tableau. Tableau versions 2019.2+ are supported.
You need an active internet connection to use the Web Data Connector.
To get started, you must add a record into the Integrated Clients table in the Cinchy domain with the below values.
| Column | Value |
|---|---|
Client Id | tableau-connector |
Client Name | Tableau |
Grant Type | Implicit |
Permitted Login Redirect URLs | |
Permitted Logout Redirect URLs | |
Permitted Scopes | Id, OpenId, Email, Profile, Roles |
Access Token Lifetime (seconds) | 3600 |
Show Cinchy Login Screen | Checked |
Enabled | Checked |
### Connect from Tableau |
Launch Tableau.
Under Connect -> To a Server select the Web Data Connector option.
Enter the URL from the Permitted Login Redirect URLs field on the Integrated Clients record created under the Prerequisites section above.
The Cinchy login screen will appear, enter your credentials
Select one or more queries to add to your data set. The result of each query will be available as a Table in Tableau. If a query has parameters, you will be prompted to provide the parameter values before you can add it to your collection.
Select the Load button.
The Cinchy query results will now be accessible for you to create your visualization.
