Automate LeanKit with Node.js

To help customers get the most out of LeanKit, we provide Web Services for automating common tasks, such as creating, updating, and moving cards on a board. In addition, there are software clients available for common programming languages and platforms, making it easier to take advantage of LeanKit's Web Services. In this article, I want to introduce the LeanKit Client for Node.js.

At a glance

What can you do with LeanKit Web Services? Here are a few examples.

  • Automate repetitive tasks, such as updating many cards at once.
  • Monitor LeanKit for specific conditions, and send notifications.
  • Synchronize information between LeanKit and another system.

The LeanKit Client for Node.js makes it easy to

  • retrieve a list of boards,
  • retrieve a board with all its lanes and cards,
  • search for cards,
  • add, update, move, and delete cards,
  • and many other tasks.

Why Node.js?

  • Node.js runs on Windows, Mac OSX, and Linux.
  • Node.js applications are written in JavaScript, arguably the most popular and universal language.
  • Node.js can easily consume and use Web Services.
  • There are thousands of free and open-source software components available to expand Node.js capabilities.
  • No special programming tools are required, just a good text editor.

Chances are systems you may wish to integrate with LeanKit also expose Web Services. Node.js is an ideal solution for connecting Web Services.

Quick start guide

Node.js vocabulary

Before we begin, it may be useful to define some common terms used in building applications with Node.js.

TermDefinition
moduleSoftware that can be used with Node.js. The LeanKit Client for Node.js is a module. 3rd-party modules are also commonly referred to as "packages."
packageOften used interchangeably with "module."
npmThe "package manager" for Node.js. It is an application used to download and install modules.

Install Node.js

If you don't already have Node.js, simply go to nodejs.org and download the installer. You can verify Node.js is installed and working from a command prompt or terminal window.

node -v

This should print to the console the version of Node.js you have installed.

Create a project folder

Next, create a folder for your application. From the command/terminal window, you can use the following. Feel free to change the name or path of the folder.

mkdir leankit
cd leankit

Install the LeanKit client

Installing the LeanKit client for Node.js is easy with npm.

npm install leankit-client

Hello LeanKit

Create a plain text file named leankit.js with a text editor. Add the following code and save the file.

// Reference the LeanKit client
const LeanKitClient = require( "leankit-client" );

// Update the following to match your LeanKit
// account and login credentials. Your account is
// host name part of the LeanKit URL you use to access
// your LeanKit boards. For example, if your URL looks like
// https://mycompany.leankit.com
// your account would be "mycompany"
const auth = {
	account: "mycompany",
	email: "me@mycompany.com",
	password: "p@ssw0rd"
};

// Create an instance of the client with your credentials
const client = LeanKitClient( auth );

// Use the client to get a list of boards
client.board.list().then( response => {
	console.log( response.data );
} ).catch( err => {
	console.log( "There was an error:", err );
} );

Now, run the Node.js application by entering the following.

node leankit.js

If all goes well, you should see a list of your LeanKit boards printed to the console.

Get a LeanKit board

The LeanKit client for Node.js makes it easy to get a board with all its lanes and other information.

Create a new JavaScript file named board.js. Add the following code, and update it to match your account. Last, save the file.

const LeanKitClient = require( "leankit-client" );
const auth = {
	account: "mycompany",
	email: "me@mycompany.com",
	password: "p@ssw0rd"
};
const client = LeanKitClient( auth );

// Change this variable to match the ID of the board
// you want to retrieve. If needed, use the previous
// sample code to list all the boards in your account
// to determine the correct ID to use.
const boardId = "123456789";

client.board.get( boardId ).then( response => {
	const board = response.data;
	console.log( board );
} ).catch( err => {
	console.error( "Error getting board:", err );
} );

Run the application using the following.

node board.js

Retrieving cards

The LeanKit client for Node.js also makes it easy to query for cards.

Create a new JavaScript file named cards.js. Add the following code, update it to match your account, and save the file.

const LeanKitClient = require( "leankit-client" );
const auth = {
	account: "mycompany",
	email: "me@mycompany.com",
	password: "p@ssw0rd"
};
const client = LeanKitClient( auth );

// Change this board number to match the ID of the board
// you want cards. If needed, use the previous
// sample code to list all the boards in your account
// to determine the correct ID to use.
const query = {
	board: "123456789",
	limit: 100
};

client.card.list( query ).then( response => {
	const cards = response.data;
	console.log( cards );
} ).catch( err => {
	console.error( "Error getting cards:", err );
} );

Run the application using the following.

node cards.js
You can use the query search criteria to further narrow your list of cards. You can also remove the `board` property to list cards from across all the boards you have access to. For example, use this query to search for card with "my card title" on any board:
const query = {
	search: "my card title"
};

Add a new card

In this final example, we will automate adding a card to a board.

Create a new JavaScript file named add-card.js. Add the following code, update it to match your account, and save the file.

const LeanKitClient = require( "leankit-client" );
const auth = {
	account: "mycompany",
	email: "me@mycompany.com",
	password: "p@ssw0rd"
};
const client = LeanKitClient( auth );
const boardId = "123456789";

// Update this value to equal the type of card
// you wish to create
const cardTypeName = "Improvement";

// First get the board, so we can get some data before creating the card
client.board.get( boardId ).then( boardRes => {
	const board = boardRes.data;

	// find the default drop lane
	const defaultDropLane = board.lanes.find( x => x.isDefaultDropLane );

	// find our card type
	const cardType = board.cardTypes.find( x => x.name === cardTypeName );

	// create a new card with minimal properties
	const card = {
		boardId,
		title: "Card created with Node.js",
		description: "This card was created using the LeanKit Client for Node.js",
		typeId: cardType.id,
		laneId: defaultDropLane.id
	};

	// make the call to create the card
	return client.card.create( card );
} ).then( cardRes => {
	console.log( `New card created: ${ cardRes.data.id }` );
} ).catch( err => {
	console.log( "error creating card:", err.statusText, err.data );
} );

Run the application using the following.

node add-card.js

If all is successful, a new card should soon appear on your board in the default drop lane!

Wrap up

The LeanKit Client for Node.js is an easy way to automate LeanKit tasks using Node.js. This introduction only scratched the surface. You can update cards, move cards, manage taskboards, add comments and attachments, and much more. For more information, you can check out the documentation and source code. And, be sure to check out the sample projects!

David Neal

David is the Developer Advocate at LeanKit. He is a family man, geek, musician, motorcyclist, speaker, software developer, and Microsoft MVP living in North Georgia. He runs on a high-octane mixture of caffeine and bacon.