Monday.com

The Monday.com example solution showcases how to connect a Teneo solution with the Monday.com REST API. The example flows in the solution demonstrate how user can be authenticated as well as how to retrieve, add and filter items on Monday.com.

monday.com

Solution contents

Monday.com integration

The solution contains a Monday.com backend integration containing methods for authentication, retrieval of items from dashboard, group as well as for adding, filtering items. Since the source code of the integration is embedded in the solution, it can be easily extended or used as a starting point for new methods.

Example flows

For each core method in the Monday.com integration, the solution contains a corresponding example flow:

User asks to retrieve items from a dashboard
User asks to retrieve items from a group
User asks to add item to a dashboard
User asks to add item to a group
User asks to filter items in a dashboard
Bot asks an user to login into Monday.com
User asks to logout from Monday.com

Authentication flow

Monday.com provides a support for OAuth authentication, API token based authentication and basic authentication methods that allow a Teneo bot to interact with Monday.com on the user's behalf. Which authentication method to use depends on factors like use case and channel. This example solution contains flow to demonstrate API token based authentication approach.

Getting started

Prerequisites

These instructions assume you have a Monday.com admin account. Alternatively, you can sign up for a free user account on Monday.com. These instructions assume you have downloaded and imported the Monday.com solution. See instructions below.

Create a Monday.com connected app

It's time to create a main workspace on Monday.com developer portal in order to perform & experience some operations by using Monday.com Teneo bot

Using your administrator account, log in to your Monday.com portal.
Go to your email account and click once on button 'Click to confirm your email address' provided by Monday.com
On Monday.com portal, select the Workspaces icon located to the left. This will open up a new section.
Select the 'Add' button located under section Main workspace.
Click on 'New Board' and type your board name as you wish on text field.
Click on 'Create Board' button. Your board is ready and would appear under Main workspace section

Generate API Key

It's important to generate an API key associated with your account in order for Teneo to have access to it.

Click on Avatar icon located at the left most bottom of Monday.com portal.
Under Account select the 'Admin' button.
Select the 'API' menu located on left side panel.
Click on the 'Generate' button and store the API key securely for later reference.

Add credentials to your solution

The solution contains a global variable MondayDotCom_sAPIKey in which an API key we have collected should be stored. We’re interested in our instance API key. People may try to use their Monday.com API key accordingly. The value of the global variable should be a type of String like this:

Variable Name	Example value	Description
MondayDotCom_sAPIKey	'sdsdfsdfOfxxxxxxxxxxxxxxxx'	Monday.com user account API key

To update the global variables, proceed as follows:

In a text editor, update each of above global variables by pasting in the values you have collected in the steps above.
In your Monday.com solution, click the 'Solution' tab and select 'Globals' in the purple navigation bar.
Select the 'Variables' tab at the top, select the variables called MondayDotCom_sAPIKey.
In the panel on the right, click 'Edit'. You can now update the value of the variable by pasting the updated string values.
When done, click 'Save All' in the top right corner.

Test in Tryout

Your solution is now ready. You can test this in Try Out by asking I want to retrieve items from dashboard. The Teneo bot would then start asking you to input for follow up questions and then answer should provide the items, which are available under a dashboard on Monday.com portal.

Example conversations

User: I want to login
Bot: Hi there! I'm a Monday.com Connector virtual assistant from Artificial Solutions.
Bot: Please enter an API key provided by Monday.com.
User: sdsdfsdfOfxxxxxxxxxxxxxxxx
Bot: Hi there! Your login has been successful!

User: I want to retrieve items from dashboard
Bot: Please choose one of the following dashboards. Note: Dashboard name is case sensitive. Dashboard1, Dashboard2
User: Dashboard1
Bot: Below are list of items from a dashboard Dashboard1. 10234533 - Item1, 10924343 - Item2

User: Can I retrieve items from a dashboard group
Bot: Please choose one of the following dashboards. Note: Dashboard name is case sensitive. Dashboard1, Dashboard2
User: Dashboard1
Bot: Please choose one of the following dashboard groups. Note: Dashboard group name is case sensitive. Group1, Group2
User: Group1
Bot: Below are list of items from a dashboard group Dashboard1 --> Group1. 10234533 - Item1, 10924343 - Item2

User: I want to add item to a dashboard
Bot: Please choose one of the following dashboards. Note: Dashboard name is case sensitive. Dashboard1, Dashboard2
User: Dashboard1
Bot: Please enter an item name.
User: My first item
Bot: New item 12043434 - My first item has been added into a dashboard Dashboard1 successfully!

User: Can I add item to a dashboard group
Bot: Please choose one of the following dashboards. Note: Dashboard name is case sensitive. Dashboard1, Dashboard2
User: Dashboard1
Bot: Please choose one of the following dashboard groups. Note: Dashboard group name is case sensitive. Group1, Group2
User: Group1
Bot: Please enter an item name.
User: My first group item
Bot: New item 1023459 - My first group item has been added into a dashboard group Dashboard1 --> Group1 successfully!

User: I want to filter items in a dashboard
Bot: Please choose one of the following dashboards. Note: Dashboard name is case sensitive. Dashboard1, Dashboard2
User: Dashboard1
Bot: How would you like to filter the items? 1.) By Group
User: By group
Bot: Please choose one of the following dashboard groups. Note: Dashboard group name is case sensitive. Group1, Group2
User: Group1
Bot: Below are list of items filtered from a dashboard Dashboard1. 10234533 - Item1, 10924343 - Item2

User: I want to logout
Bot: Your logout has been successful!

For simplicity, the bot answers in this solution are text only. Depending on the channel, interactive cards can be added, for example to add buttons or allow the user to select items from a list.

More on authentication

Monday.com offers multiple authentication methods including OAuth authentication, Basic authentication and API token key based authentication by using user id & API key that developers can use to allow their users to authenticate with Monday.com. Which authentication flow to use depends on the type of application and the use case.

This Monday.com solution contains a flow called 'Bot asks an user to login into Monday.com'. This flow is responsible to set a value of global variable called MondayDotCom_bHasUserLoggedIn which is included at the beginning of each other flows that checks the user's authentication to access the flows. This flow checks if the global variables MondayDotCom_sAPIKey contains values which is needed to perform API requests. If the MondayDotCom_bHasUserLoggedIn variable is 'false', this flow answers a user authentication failure message.

By default, the Monday.com 'Bot asks an user to login into Monday.com' flow uses the stored credentials from global variables to authenticate the user. This flow uses Monday.com's API key based authentication mechanism, which provides instructions in the getting started section on this page explain how to prepare your solution using this authentication approach.

This authentication uses stored credential from a global variable MondayDotCom_sAPIKey to prepare an authentication with Monday.com. MondayDotCom_sAPIKey authorization header value checks an access against Monday.com instance URL stored on MondayDotCom_sInstanceEndPointUrl and return a successful authentication.

The value stored in the global variable MondayDotCom_sAPIKey can be used for subsequent requests that require authentication across flows in the Monday.com solution. The global variable is used by the Monday.com integration for the various REST requests.

The solution uses the stored credentials approach by default, mostly because it is easiest and quickest to get started. However, because this authentication flow passes the user’s credentials back and forth it is advised to use this authentication method for development purposes only. Additionally, using stored credentials means that all objects created by the bot are created by the same user. Therefore, it might be preferred to implement an authentication flow that enables Teneo to interact with Monday.com on the user's behalf.

However, this authentication flow can still be used in production grade only when a frontend connector or a channel connector supplies necessary user credentials instead of hardcoding them in Teneo in a more secured way by using any industrial standard encryption techniques.

The authentication flow for the API Key based authentication in combination with Teneo roughly looks like this:

Monday.com - diagram

For more details on Monday.com and API Key based authentication, see: Digging Deeper into API token in Monday.com

Download

Download the solution here.
Import the solution into Teneo. For more details see: How to import solutions.