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.

Term Definition
module Software 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."
package Often used interchangeably with "module."
npm The "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
var LeanKitClient = require( "leankit-client" );

// Update this variable to the name of your LeanKit
// account, which can be found in the URL you use
// to access your LeanKit boards. For example,
// https://mycompany.leankit.com
var accountName = "mycompany";

// Update this variable to your email address
var email = "me@mycompany.com";

// Update this variable to your LeanKit password
var password = "p@ssw0rd";

// Create an instance of the client with your credentials
var client = new LeanKitClient( accountName, email, password );

client.getBoards( function( err, boards ) {
  if ( err ) console.error( "Error getting boards:", err );
  console.log( boards );
} );

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 download an entire board with all its lanes and cards. Create a new JavaScript file named board.js. Add the following code, update it to match your account, and save the file.

var LeanKitClient = require( "leankit-client" );
var accountName = "mycompany";
var email = "me@mycompany.com";
var password = "p@ssw0rd";
var client = new LeanKitClient( accountName, email, password );

// 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.
var boardId = 12345678;

client.getBoard( boardId, function( err, board ) {
    if ( err ) console.error( "Error getting board:", err );
    console.log( board );
} );

Run the application using the following.

node board.js

Depending on the size of your board, a lot of information could be output to the console! Let's update the client.getBoard() to narrow the output to just the cards in the first lane.

client.getBoard( boardId, function( err, board ) {
    if ( err ) console.error( "Error getting board:", err );

    // Get the active lanes from the board
    var lanes = board.Lanes;

    // Get the first lane (index starts at 0)
    var firstLane = lanes[ 0 ];

    // Get the cards in the lane
    var cards = firstLane.Cards;

    // Loop through the cards and output basic information
    for (var i = 0; i < cards.length; i++) {
        var card = cards[ i ];
        console.log( card.Id, card.Title, card.TypeName );
    }
} );

Save board.js and run the application again.

node board.js

Using search to find cards

The LeanKit client for Node.js also makes it easy to search for cards. Create a new JavaScript file named search.js. Add the following code, update it to match your account, and save the file.

var LeanKitClient = require( "leankit-client" );
var accountName = "mycompany";
var email = "me@mycompany.com";
var password = "p@ssw0rd";
var client = new LeanKitClient( accountName, email, password );
var boardId = 12345678;

// Update the search options to match your criteria
// Use SearchTerm to search card title and description,
// and optionally comments and tags.
var searchOptions = {
    SearchTerm: "",
    SearchInBacklog: false,
    SearchInBoard: true,
    SearchInRecentArchive: false,
    SearchInOldArchive: false,
    IncludeComments: false,
    IncludeTags: false,
    Page: 1,
    MaxResults: 20
};

client.searchCards( boardId, searchOptions, function( err, response ) {
    if ( err ) console.error( "Error searching cards:", err );
    console.log( response.Results );
    console.log( "Total Results:", response.TotalResults );
} );

Run the application using the following.

node search.js

You can narrow down the output similar to the previous board.js example. And, there are more search options available, such as assigned users and date filtering.

For a more complete example on searching for cards and saving results to a CSV file, see the node search project in our open-source GitHub repository. CSV files can be opened with Microsoft Excel or Google Sheets.

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.

var LeanKitClient = require( "leankit-client" );
var accountName = "mycompany";
var email = "me@mycompany.com";
var password = "p@ssw0rd";
var client = new LeanKitClient( accountName, email, password );
var boardId = 12345678;

// Properties of the new card to add
var card = {
    Id: 0,
    Title: "LeanKit card created with Node.js",
    Description: "This card was created using the LeanKit Client for Node.js.",
    TypeId: 0,
    Priority: 1,
    Size: 0,
    DueDate: "",
    Tags: "nodejs",
    AssignedUserIds: []
};

// This will be the relative position of the card
// in the lane. 0 means the card will be added
// to the top of the lane ahead of any other cards.
var position = 0;


// We need some information about the board,
// such as the default card type and drop lane,
// so we'll get that information first
client.getBoardIdentifiers( boardId, function( err, boardIdentifiers ) {
    if ( err ) {
        console.error( "Error getting board identifiers:", err );
        return;
    }

    // Find the default drop lane
    var defaultDropLane = null;
    for (var i = 0; i < boardIdentifiers.Lanes.length; i++) {
        var currentLane = boardIdentifiers.Lanes[ i ];
        if ( currentLane.IsDefaultDropLane === true ) {
            defaultDropLane = currentLane;
            break;
        }
    }

    // Find the default card type
    var defaultCardType = null;
    for (var j = 0; j < boardIdentifiers.CardTypes.length; i++) {
        var currentType = boardIdentifiers.CardTypes[ j ];
        if ( currentType.IsDefault === true ) {
            defaultCardType = currentType;
            break;
        }
    }

    // Set the card type
    card.TypeId = defaultCardType.Id;

    // Add the card
    client.addCard( boardId, defaultDropLane.Id, position, card, function( err, response ) {
        if ( err ) console.error( "Error adding card:", err );
        console.log( response );
    } );

} );

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.