#1002 - OIC - Integrating with Monday.com using GraphQL adapter

Introduction

Here's my first board on Monday.com. 

Let's check out their api, firstly in Postman.

Starting point is the Monday.com API documentation here.

You will need an api key to authenticate requests. Key can be created here - 

 

Save the api key for future use.

First api I try is the following - 

query { users { id, name } }

Set Authorization to the api key value.

Short Introduction to GraphQL

Let's have a quick look at GraphQL itself, before starting with the adapter in OIC. 

GraphQL queries or operations can be used to retrieve data (query) or create/update/delete data (mutation). You will see these 2 types in the examples below.

GraphQL has a couple of advantages in respect of REST.

1. there is a single endpoint - you will see this in my Monday.com examples - https://api.monday.com/v2

2. with GraphQL queries I can easily pull in related data making it ideal for large and complex queries.

3. the response payload definition is flexible, each client can request what they want

I'm sure there are more, but they're the ones that hit me. 

Now to the syntax, the query above - query { users { id, name } } - is like a SQL statement - Select id, name from users;

You can pass arguments (black below) into a query and specify fields (red below) to be returned e.g.

query { boards (ids: 1362027599) {name, board_kind}}

You will have to define variables for arguments, when using the GraphQL adapter in OIC, but more about that later.

Using the GraphQL adapter in OIC

Let's try the postman GraphQL request in OIC - begin by creating a GraphQL connection for Monday.com.

Now to the integration - 

The GraphQL invoke is configured as follows - based on the postman example - query { users { id, name } }

Note the Try Query feature - 

Now let's try another query - this one retrieves board information - remember, I have only 1 board currently - Sales Board.

Here it is in Postman - 

query { boards (ids: 1362027599) {name, board_kind}}

You can read this as follows - SELECT name, board_kind FROM Boards where id in [id list]

Now to the configuration of the OIC invoke for this - 

Back to the Monday.com api docs - here it is for the Boards object - 

The argument, ids, is defined as a list of ints. Hence my GraphQL Variable definition above - { "v_boardIds": [123]}

The GraphQL query begins with a declaration of the variable to be used - 

query ($v_boardIds: [Int]!)

Note the type definition [Int]!

Then we pass the pass the variable into the query - 

boards(ids: $v_boardIds) {

    name

    state

    id

    permissions

  }

Simple stuff - let's test this - 

Syntactically correct, but no data found. I now re-test with a valid id - 

Now to something more advanced - how about creating a new board?

Let's try this in Postman - 

The word mutation may seem strange but it is just the graphQL term for insert/update, akin to REST POST etc.

mutation {

  create_board (board_name: "my board", board_kind: public) {

    id

  }

}

Check out the new board in Monday.com - 

Now to the OIC equivalent - 

mutation ($v_newBoard: String!) {

  create_board(board_name: $v_newBoard, board_kind: public) {

    id

  }

}

I click Try Query and test this - setting the variable to Bord Bainne.

Back in Monday.com - 

Delete is easy - let's get rid of Bord Bainne. I need the id, which I find here - 

The id is - 1363088938

Here is delete in Postman -

I check in Monday.com - 

Back to OIC - 

1363070084 is the id of the board - my board.

Querying data and Updating Boards

Boards are central to monday.com, all your stuff goes in there. 

A board contains columns and rows.

Rows are referred to as items.

We also have groups, essentially groups of rows, and, finally, columns - we know what they are.

Let's look for a list of the projects - 

I got the "column" name via the following query - 

 

Let's delete Project3 - note the id - 1362027646

I validate in the UI - 

Let's look at Groups - 

This is analogue to the UI.

Next step is to create a new row in the This month group.

Validate in the UI - 

Here's the mutation - 

mutation {

  change_multiple_column_values (item_id: 1364626424, board_id: 1362027599, 

  column_values: "{\"project_status\": \"Working on it\", \"date\":\"2024-07-01\",\"priority_1\":\"High\", \"numbers\": \"999\"}"

  ) {

    id

  }

}

The result in the UI -

Let's implement this in OIC.

Updating Boards via OIC 

Here is a simple integration that creates a new project row and then updates the row with the relevant values - 

 

Here is the query - 

mutation ($var_boardId: Int!, $var_group_id: String!, $var_projectName: String) {

  create_item(board_id: $var_boardId, group_id: $var_group_id, item_name: $var_projectName) {

    id

  }

}

Validate in the UI - 

Now the change_multiple_column_values query - 

Here is the query - 

mutation ($var_boardId: Int!, $var_itemId: Int!, $var_columnValues: JSON!) {

  change_multiple_column_values(item_id: $var_itemId, board_id: $var_boardId, column_values: $var_columnValues) {

    id

  }

}

Note the variable - var_columnValues which has the type JSON.

I set this in the map action - 

Var Column Values is set to - 

concat ('{"project_status": "', /nssrcmpr:execute/ns22:request-wrapper/ns22:status, '"', ",", '"date": "', /nssrcmpr:execute/ns22:request-wrapper/ns22:dueDate, '"', ",", '"priority_1":"', /nssrcmpr:execute/ns22:request-wrapper/ns22:priority, '"', ",", '"numbers": "', /nssrcmpr:execute/ns22:request-wrapper/ns22:budget, '"', " }" )

Let's activate and test the integration -

I validate in monday.com -